创见博客
npm发包
七崽爱吃小饼干2026/02/13阅读 2专栏 JavaScript

npm 发包流程

一、npm 发包的核心定义

「npm 发包」（npm publish）本质上是将你本地编写的 JavaScript/Node.js 代码包，上传并发布到 npm 官方公共仓库（npmjs.com）的过程。

简单来说：

  • 你是「包的开发者」，把自己写的可复用代码（比如一个工具函数、UI 组件、框架插件等）打包；
  • 通过 npm publish 命令，把这个包上传到 npm 官方服务器；
  • 上传成功后，全世界的开发者都能通过 npm install 你的包名 下载、安装并使用你的代码。

举个通俗例子理解

npm 仓库就像一个「代码应用商店」：

  • 你开发了一个好用的「日期格式化工具」，把它打包成规范的 npm 包；
  • 「发包」就是把这个工具上架到这个「应用商店」；
  • 其他开发者需要格式化日期时，不用自己写代码，直接从商店「下载」（npm install）你的工具就能用。

发包的核心价值

  1. 代码复用：你写的通用功能（比如表单验证、请求封装），发布成包后，自己的多个项目、甚至其他开发者都能直接用，不用重复写；
  2. 开源分享：向社区贡献代码，帮助更多开发者解决问题；
  3. 团队协作：在公司内部发布私有包（需配置私有 npm 源），方便团队成员共享内部工具/组件。

补充：发包≠仅发布到公共仓库

  • 「公开发包」：发布到 npm 公共仓库，所有人可见可用；
  • 「私发包」：发布到私有 npm 仓库（如公司内部仓库、npm 付费私有仓库），仅指定人群可见可用。

总结

  1. npm 发包的本质是：将本地符合规范的代码包上传到 npm 仓库（公共/私有），供他人/自己下载使用；
  2. 核心操作是执行 npm publish 命令，前提是包有唯一名称、规范的版本号和 package.json 配置；
  3. 核心价值是实现代码复用、开源分享或团队内部协作。

二、npm 发包流程的两种核心场景

场景 1：手动交互发布（基于 OTP 验证）

  • 核心定义：在本地终端手动执行 npm login 和 npm publish，全程需要输入账号密码 + 2FA 生成的 6 位动态 OTP 码完成验证，是「人直接操作」的发布方式。
  • 适用场景：
    • 本地开发调试后，手动发布少量包；
    • 对安全性要求极高，不想留存令牌在本地/CI 环境；
    • 临时发布包，无需自动化流程。
  • 核心操作特征：
    1. 需先在 npm 账号开启 TOTP 类型 2FA；
    2. npm login 时要输入 OTP 码完成登录；
    3. npm publish 时需再次输入 OTP 码（或通过 --otp=xxx 参数传入）。

场景 2：非交互/CI 发布（基于新版 Granular Token）

  • 核心定义：通过生成 npm 官方的「细粒度访问令牌（Granular Token）」，替代账号密码 + OTP 验证，无需手动输入任何验证码，适合自动化/无人值守的发布方式。
  • 适用场景：
    • 持续集成/持续部署（CI/CD）流程中自动发布（如 GitHub Actions、Jenkins）；
    • 批量发布多个包，或频繁更新包，不想每次手动输入 OTP；
    • 服务器/容器环境中发布包，无交互式终端。
  • 核心操作特征：
    1. 无需本地 npm login，直接将令牌配置到环境/.npmrc 文件；
    2. 生成令牌时必须勾选「Bypass 2FA」和「Publish packages」权限；
    3. npm publish 时无需输入任何验证码，直接执行即可。

两种场景核心差异对比

维度手动交互发布（OTP）非交互/CI 发布（Granular Token）
验证方式账号密码 + 6 位 OTP 动态码细粒度令牌（内置权限 + 绕过 2FA）
交互性需手动输入验证码无交互，全程自动化
适用场景本地手动发布CI/CD、自动化发布
安全性需保管好验证器/恢复码需妥善保管令牌（泄露即有风险）

总结

  1. 手动交互发布（OTP）：适合本地少量、临时发布，核心是「输入动态验证码」完成 2FA 验证；
  2. 非交互/CI 发布（Granular Token）：适合自动化发布，核心是「生成带 Bypass 2FA 权限的细粒度令牌」，免手动验证。

三、发包流程

前置条件

  • 已注册 npm 账号（未注册先去 npm 官网 注册）；
  • 本地已安装 Node.js + npm（建议 npm 版本 ≥ 9.0.0，兼容新版令牌）；
  • 确保使用 npm 官方源（非淘宝镜像）。

第一步：初始化/准备发包项目

  1. 创建/进入项目目录（已有项目跳过）：
    bash
    mkdir my-npm-pkg && cd my-npm-pkg
  2. 初始化 package.json（核心配置需正确）：
    bash
    npm init -y # 快速初始化，之后手动修改关键配置
    关键配置示例（package.json）：
    json
    {
  "name": "my-unique-pkg-name", // 包名必须唯一（npm 官网搜是否被占用）
  "version": "1.0.0", // 语义化版本，首次发布用 1.0.0
  "main": "index.js", // 入口文件
  "description": "带 2FA 验证的 npm 包示例",
  "author": "你的名字 <你的邮箱>",
  "license": "MIT",
  "keywords": ["npm", "2FA", "granular-token"]
}
  3. 编写核心代码（示例 index.js）：
    javascript
    function greet(name) {
  return `Hello ${name}! 👋`;
}
module.exports = { greet };
  4. 可选配置：添加 README.md（说明包的使用方式）、.gitignore（忽略 node_modules 等文件）。

第二步：配置 2FA 并准备发布凭证

场景 1：手动交互发布（本地用 OTP 验证）
1. 开启 npm 账号 2FA
  • 登录 npm 官网 → 右上角头像 → Account Settings → Two-Factor Authentication；
  • 选择验证方式（推荐 TOTP，如微信小程序「身份验证器」/Google Authenticator）：
    1. 扫描二维码绑定设备，记录备用恢复码（丢失设备时用）；
    2. 输入验证器生成的 6 位动态码，完成 2FA 开启。
2. 本地登录 npm（带 2FA）
bash
# 切换到 npm 官方源（关键）
npm config set registry https://registry.npmjs.org/

# 登录账号，会触发 2FA 验证
npm login
# 按提示输入：
# Username: 你的 npm 用户名
# Password: 你的 npm 密码
# Email: (this IS public) 你的注册邮箱
# Enter one-time password: 验证器生成的 6 位 OTP 码
  • 验证登录成功：npm whoami（输出用户名即成功）。
场景 2：非交互/CI 发布（用新版 Granular Token，免 OTP）
1. 生成 Granular Access Token（细粒度令牌）
  • 登录 npm 官网 → 右上角头像 → Access Tokens → Generate New Token → 选择「Granular Access Token」；
  • 配置令牌权限（核心）：
    • Token name：自定义名称（如 ci-publish-token）；
    • Expiration：有效期（最长 90 天，建议按需设置）；
    • Package access：选择「Specific packages」→ 勾选你要发布的包（或「All packages」）；
    • Permissions：
      • 勾选「Publish packages」（发布权限）；
      • 勾选「Bypass 2FA」（关键：绕过 OTP 验证）；
    • 可选：限制 IP/CIDR（提高安全性）；
  • 点击「Generate token」，立即复制令牌（仅显示一次，丢失需重新生成）。
2. 配置令牌到本地/CI 环境
bash
# 方式 1：临时配置（仅当前终端有效）
npm config set //registry.npmjs.org/:_authToken=你的 Granular Token

# 方式 2：永久配置（写入 ~/.npmrc 文件，推荐）
echo "//registry.npmjs.org/:_authToken=你的 Granular Token" >> ~/.npmrc

# 验证令牌有效：无需 login，直接执行 npm whoami 会输出用户名
npm whoami

第三步：发布包（分场景执行）

场景 1：手动交互发布（输入 OTP）
bash
# 方式 1：发布时手动输入 OTP
npm publish
# 提示 Enter one-time password: 输入验证器的 6 位 OTP 码

# 方式 2：直接传 OTP 发布（无需手动输入）
npm publish --otp=123456 # 替换为你的 6 位 OTP 码

# 若发布作用域包（如 @你的用户名/包名），需加 --access public
npm publish --access public --otp=123456
场景 2：非交互/CI 发布（用 Granular Token，免 OTP）
bash
# 直接发布，无需输入任何验证码
npm publish

# 作用域包同样直接发布
npm publish --access public

第四步：发布后验证与维护

  1. 验证发布成功：

    • 访问 https://www.npmjs.com/package/你的包名，能看到包信息即成功；
    • 本地测试安装：npm install 你的包名，引入使用验证功能。

  2. 更新包（修改代码后）：

    bash
    # 升级版本号（语义化版本）
npm version patch # 小修复：1.0.0 → 1.0.1
# npm version minor # 新增功能：1.0.1 → 1.1.0
# npm version major # 不兼容更新：1.1.0 → 2.0.0

# 重新发布（按场景选择方式）
# 场景 1：npm publish --otp=123456
# 场景 2：npm publish

  3. 撤销包（谨慎，仅限发布 72 小时内）：

    bash
    # 场景 1：带 OTP 撤销
npm unpublish 包名@版本号 --force --otp=123456
# 场景 2：用 Granular Token 撤销
npm unpublish 包名@版本号 --force

第五步：发布后恢复镜像（可选）

bash
# 切回淘宝镜像（国内开发更快捷）
npm config set registry https://registry.npmmirror.com/

关键注意事项

  1. Granular Token 是 2026 年 npm 唯一支持的令牌类型，经典令牌（Classic Token）已失效；
  2. 开启 2FA 后，恢复码一定要妥善保存，丢失设备后可用于找回账号；
  3. Granular Token 权限最小化：仅给需要的包分配发布权限，避免「All packages」；
  4. 版本号不能重复发布，更新包必须先升级 version 字段；
  5. 作用域包发布时必须加 --access public，否则会发布为私有包（需付费）。

总结

  1. 核心流程：项目初始化 → 配置 2FA/生成 Granular Token → 登录/配置令牌 → 带 OTP/令牌发布；
  2. 手动发布选「OTP 验证」：登录和发布时均需输入 6 位动态码；
  3. CI/非交互发布选「Granular Token」：生成时勾选「Bypass 2FA」，发布无需验证码，且权限更可控。
评论
0/100