从零到一：发布你的第一个 npm 开源库（2025 终极指南）
作者：@源滚滚
日期：2025-08-15
为什么要发布 npm 包？
- 个人品牌：简历上极具说服力的开源贡献
- 技术成长：倒逼自己写出更高质量的代码与文档
- 社区回馈：你的轮子可能正是别人的救命稻草
1. 环境准备
| 工具 | 版本要求 | 备注 |
|---|---|---|
| Node.js | ≥ 18 | 内置 npm ≥ 9 |
| Git | ≥ 2.30 | 用于版本管理与 CI |
| 账号 | npmjs.com / GitHub | 用于发布 & 托管 |
2. 项目初始化（3 分钟搞定）
2.1 使用官方脚手架
# 创建目录并进入
mkdir my-hello-lib && cd $_# 一键初始化库模板（官方推荐）
npm create lib@latest
# 交互式填写包名、描述、作者等信息
生成的目录结构：
my-hello-lib
├── src
│ └── index.ts # 入口文件
├── test
│ └── index.test.ts
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE
2.2 本地开发
npm run dev # 启动 Rollup 监听
npm run test # Jest 单测
npm run storybook # 可选，可视化调试
3. 代码组织最佳实践
| 维度 | 推荐做法 | 反面教材 |
|---|---|---|
| 入口 | 使用 exports 字段声明多种导出 | 只写 main |
| 类型 | 自动生成 .d.ts | 手写声明文件 |
| 样式 | CSS Modules / Tailwind | 全局样式污染 |
| 体积 | 按需打包，Tree-shaking | 把 React 打进去 |
示例 package.json
{"name": "my-hello-lib","version": "0.1.0","type": "module","exports": {".": {"import": "./dist/index.mjs","require": "./dist/index.cjs","types": "./dist/index.d.ts"},"./dist/style.css": "./dist/style.css"},"files": ["dist"]
}
4. 发布全流程
4.1 登录 npm（务必切换官方源）
# 临时使用官方源
npm login --registry https://registry.npmjs.org# 验证登录成功
npm whoami
4.2 语义化版本
npm version patch # 0.1.0 → 0.1.1 修 bug
npm version minor # 0.1.0 → 0.2.0 新功能
npm version major # 0.1.0 → 1.0.0 不兼容变更
4.3 构建 & 发布
npm run build # Rollup / tsup / unbuild
npm publish --access public
⚠️ 首次发布需加
--access public，私有包需付费。
5. 自动生成变更日志
使用 changesets 一键生成 CHANGELOG.md：
npx changeset init # 初始化
npx changeset # 选择改动类型
npx changeset version # 更新版本与日志
git add . && git commit -m "chore: bump versions"
6. GitHub Actions 持续集成
.github/workflows/ci.yml
name: CI & Release
on:push:branches: [main]jobs:test:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- uses: actions/setup-node@v4with:node-version: 20registry-url: https://registry.npmjs.org- run: npm ci- run: npm test- run: npm run build- if: github.ref == 'refs/heads/main'run: npm publishenv:NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
在 GitHub → Settings → Secrets 添加 NPM_TOKEN。
7. 营销与社区增长
| 渠道 | 操作要点 |
|---|---|
| GitHub | README 动图 + issue 模板 + discussion |
| 掘金 / 知乎 | 发布实战文章，贴上 npm badge |
| Twitter / X | 附上 #npm #OpenSource 标签 |
| 交流群 | 提供最小复现仓库，快速响应反馈 |
8. 常见坑与解决方案
| 症状 | 原因 | 解决 |
|---|---|---|
| 404 未找到包 | 镜像源错误 | 切换官方源 |
| 发布失败 403 | 包名已被占用 | npm view <name> 确认后改名 |
| 类型丢失 | 忘记生成 .d.ts | tsconfig.declaration=true |
| 体积 1 MB+ | 把 dev 依赖打进去 | rollup-plugin-peer-deps-external |
9. 彩蛋：一条命令查看全球下载量
npx npm-stats-cli my-hello-lib
10. 结语
发布 npm 包不是终点，而是与全球开发者协作的起点。
立即行动：把今天写的 hooks 或 utils 抽出来，30 分钟后你将拥有第一个开源作品。