说实话,npm 包发布这件事,表面上看就是一条 npm publish 命令,但我第一次完整走下来的时候,踩的坑比想象中多得多。比如登录时 registry 还是淘宝镜像,publish 一直提示 403;后来换回官方源,又因为包名被占、files 字段没配好,把一堆不该进包的文件全打进去了。这篇指南算是我把整个发布流程完整捋过之后的记录,适合已经能写 Node 工具、但还没把自己代码发布成 npm 包的开发者,也适合那些发布过一次但被各种边界问题卡住的人。
实际上,一个 npm 包从代码写完到别人能 npm install 它,中间隔着包结构设计、构建产物配置、本地调试、registry 登录、版本管理、废弃与撤回等一整套环节。你不需要一次性全掌握,但第一次发布前按顺序过一遍,后面再发就轻车熟路了。下面我按自己的实操经验,从发布前决策开始,一直讲到后续维护和常见报错,尽量把每个环节的为什么也说清楚。
1. 发布前想清楚的三件事
1.1 你要发布的到底是个什么东西
很多新手上来就 npm init -y 然后写代码,结果发布出来的包四不像。第一步应该先明确包的形态,因为它直接决定 package.json 怎么配、要不要构建、要不要写 bin 字段。
常见的 npm 包大致分四类:
- 工具库:比如 lodash、dayjs 这种,被其他项目引用,导出函数或类。这类包需要配置 main/module/types,通常还要构建产物。
- CLI 工具:比如 vue-cli、eslint 这类,安装后通过命令行执行。这类包必须有 bin 字段,而且入口文件第一行要有
#!/usr/bin/env node。 - 组件库:主要面向 React/Vue 生态,除了 JS 逻辑还有样式、类型文件。这类包对 exports 字段的要求更严格,还要考虑 sideEffects。
- 配置包:比如 eslint-config-xxx、prettier-config-xxx,本质上是导出 JSON 或 JS 配置,通常不需要构建。
我自己发布过的工具库里,纯函数库最简单,CLI 工具最容易漏 bin 配置,组件库最费事。你写代码前先问自己一句:别人装了这个包之后,是 import 它、执行它,还是直接读取它?答案不同,后面所有配置都不同。
1.2 包名、作用域和版本号怎么定
包名是发布时的第一道关卡,因为 npm 上的名字是全局唯一的。命名规范上,npm 要求小写字母,可以用连字符和下划线,但不能有空格,不能用大写。个人经验是尽量用 xxx-utils、@scope/xxx 这种格式,既符合直觉又不容易冲突。
作用域包(scoped package)是解决命名冲突和权限隔离的关键。@scope/name 这种包名天然属于某个账号或组织,其他人没法占用。对于公司内部工具,强烈建议使用 @公司名/工具名 的格式,后续发布到私有源也方便。对于个人开源,如果包名没被占用,用普通短横线命名也行。
确定包名之前,先查一下是否已被占用:
bash复制npm view your-package-name
如果返回一堆信息,说明名字被占了;如果报 404,说明这个名字可用。版本号方面,遵循语义化版本 SemVer:主版本破坏性变更、次版本加功能、补丁修 bug。0.x 阶段比较自由,但一旦上了 1.0.0,就要对自己的版本纪律负责。我第一次发布时直接定了 1.0.0,后来才发现 API 还很不稳定,结果频繁发 breaking change,对早期用户很不友好。现在我的建议是:还没稳定之前,0.x 随便发,稳定了再上 1.0.0。
1.3 发行端和安装端不是一回事:npm、cnpm、pnpm 怎么选
我看很多人在讨论 npm 和 cnpm 的区别、npm 和 pnpm 的区别,但在包发布这件事上,要分清发行端和安装端。
发布的时候,你是在和 npm registry 打交道。官方源是 registry.npmjs.org,国内常用镜像源是 registry.npmmirror.com 这类。发布动作本身用 npm 官方客户端就行,但 registry 一定要指向你真正想发布到的仓库。如果你用 cnpm 客户端,它默认可能就指向镜像源了,往镜像源 publish 是非常不推荐的操作,镜像源一般也不接受用户发布代码。
安装端则是另一回事。用户可以用 npm、cnpm、yarn、pnpm 任选一种来安装你的包。这里就有个现实问题:不同包管理器的依赖解析逻辑不同。pnpm 用符号链接,node_modules 结构是严格缩进式的,不会把传递依赖提升到顶层;npm 和 yarn 则会提升依赖。作为包作者,你不能假设用户一定用 npm,更不能假设某个传递依赖一定存在于用户项目的 node_modules 顶层。所以包里的 dependencies 和 peerDependencies 必须写全、写准,不能靠“用户环境里碰巧有某个包”。
另外,pnpm 安装出的依赖树和 npm 不同,但作为发布者,你本地检查产物时还是应该用 npm 装一遍、用 pnpm 装一遍,双保险。至少保证包本身不依赖 hoisting 行为。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 包工程结构设计与构建配置
2.1 目录结构怎么摆,构建产物放哪
一个典型 npm 工具包的结构,我推荐这样:
text复制my-pkg/
├── src/
│ └── index.ts
├── dist/
│ ├── index.js
│ ├── index.mjs
│ └── index.d.ts
├── test/
│ └── index.test.ts
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── README.md
└── LICENSE
src 放源码,dist 放构建产物,test 放测试,package.json 是核心。有一个很关键的思路:发布到 npm 的应该是 dist 编译后的产物,而不是 src 源码。当然如果只是纯 JS 零依赖小工具,不构建直接发布 src 也行,但一旦用了 TypeScript 或 JSX,就必须要构建。
dist 目录里通常需要 CJS 和 ESM 两种格式,外加类型声明 d.ts。Node 生态现在双格式混用很普遍:老项目 require 你的包,新项目 import 你的包,如果只发一种格式,就有一半用户用不了。
2.2 package.json 核心字段逐个说
package.json 是整个 npm 包的说明书。发布前
