npm 发包流程

npm

一、你真的需要发包吗？

不是所有代码都值得发 npm。

一般适合发包的情况是：

  • 通用工具函数 / SDK
  • 多个项目都会用到的逻辑
  • 希望别人能直接 npm install 用
  • 公司内部的私有包

如果只是单项目用的小工具，放在仓库里反而更省事。

二、npm 账号

如果你已经有账号，可以直接跳过。

1
npm login

按提示输入：

  • username
  • password
  • email

登录成功后确认一下：

1
npm whoami

能看到用户名，说明 OK。

三、项目配置

重点关注 package.json，字段说明：

1
2
3
4
5
6
7
8
9
10
{
  "name": "@your-scope/your-package",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "xxx"
  }
}

坑点一：name

  • 不能有大写字母
  • 不能和 npm 上已有的包重名
  • 强烈建议使用 scope：@scope/name

scope 是为了防撞名。

坑点二：version

npm 的规则很简单粗暴：

版本号不变，绝对发不了包

推荐用 npm 自带命令管理版本：

1
2
3
npm version patch   # 修 bug
npm version minor   # 加功能
npm version major   # 破坏性变更

它会自动：

  • 修改 package.json
  • 打 git tag（如果是 git 仓库）

四、控制发布内容

npm 默认会把几乎所有文件都发上去。

如果你不控制，可能会把这些一起发布：

  • src
  • test
  • 各种配置文件
  • 本地脚本

推荐方式：使用 files

1
"files": ["dist"]

这是白名单机制，最安全、最直观。

发布前一定做的一步
1
npm pack

它会生成一个 .tgz 文件，相当于发布预览。
解压看一眼，确认里面真的是你想让别人安装的内容。

五、构建

如果你用的是：

  • TypeScript
  • Babel
  • 打包工具

那基本流程一定是：

1
npm run build

确保：

  • dist/ 真实存在
  • main / types 指向的文件真的在包里

npm 不会自动 build，你不 build，它就发“空气”。

六、发布

普通包

1
npm publish

scope 包

1
npm publish --access public

如果不加这个参数，十有八九会遇到权限或 private 相关报错。

七、验证

别半场开香槟，验证下：

1
npm view your-package-name

或者新建目录测试安装：

1
npm install your-package-name

能装、能用，才算真的完成。

八、坑点回顾

❌ 忘了改 version

解决方案只有一个：
改版本号，再发。

❌ main / types 写对了，但文件不存在

表现是：安装成功，一 import 就炸。

排查思路：

  • 文件路径是否真实存在
  • npm pack 后包里有没有这个文件

❌ 不该发布的文件被发上去了

解决方案：

  • 用 files 控制范围
  • 每次发包前 npm pack

❌ 二级认证（2FA）导致发布失败 / CI 发不了包

很多人第一次开 2FA，是在“安全感”里翻车的。

常见报错/表现：

  • 本地 npm publish 要求输入一次性验证码（OTP）
  • CI 里 npm publish 直接失败（因为没人能交互式输入 OTP）
  • npm login/npm publish 提示你需要 --otp=xxxxxx
  • 使用了 token 但仍然提示 2FA 或权限不足

排查与解决思路：

  1. 先确认你账号的 2FA 策略
    在 npm 官网的账户安全设置里，2FA 常见有两种：
  • 仅对“发布/修改包”启用 2FA（推荐，且对自动化更友好）
  • 对“登录”也启用 2FA（更严格，但会让 CI/脚本更麻烦）

如果你把 2FA 开在“登录”，那 CI 里用用户名密码登录基本走不通。

  1. 本地发布：按需加 --otp
    当提示 OTP 时，直接带上：
  • npm publish --otp=123456

OTP 有时间窗口，输慢了就会失效。

  1. CI/自动化发布：不要用交互式登录，改用 Token
    正确姿势是：
  • 在 npm 创建 Automation Token（或者至少是 Publish 权限的 token）
  • 在 CI 里写入 NPM_TOKEN，通过 .npmrc 使用 token

关键点：CI 需要的是“非交互式凭证”，而不是 OTP。

  1. 注意：2FA + Token 不是“随便一配就行”
  • 如果你启用了“对登录也 2FA”，某些流程下 token 仍可能被限制/需要额外配置
  • 确保 token 具备发布范围（scope）的权限
  • scope 包发布仍可能需要 --access public
  1. 强烈建议保存 Recovery Codes（恢复码）
    手机丢了/验证器没了，恢复码是你找回发布权限的最后一根绳。

总结：本地发布可以 --otp，自动化发布要用 token；2FA 开在“发布”通常比开在“登录”更符合实际工程流程。