npm 发包完整实践与避坑指南

不久前在维护一个跨项目通用的底层算法库时,需要将其独立打包发布到 npm 官方公有仓库(如 @scope/pkg 或独立包)。虽然平时也有零星的发包经验,但由于流程未做标准化沉淀,实际操作时很容易踩入一系列隐蔽暗坑:

  • 命令行登录遭遇 403 Forbidden 与 Cloudflare / 2FA 阻断;
  • package.json 中的 version 与 Git Tag 脱节,难以回溯追溯历史;
  • 误把未编译源码、测试用例或敏感环境文件推向公网镜像;
  • 现代前端生态下,打包出的产物无法同时兼顾 ESM 与 CommonJS(Dual Package Hazard);
  • 踩中 npm 极其严苛的 “24 小时禁止重复发布同名版本” 撤包惩罚机制。

本文将结合多次开源发包排坑经历,系统梳理一套现代 npm 发包的标准化工作流、工程配置与避坑救砖指南。


一、登录与网络鉴权避坑

要发布 npm 包,首先需要在本地终端登录 npm 官方账号:

1
npm login

但在实际操作中,很多开发者在这一步就会遭遇拦截:

1
403 Forbidden - PUT https://registry.npmjs.org/-/user/org.couchdb.user:<username>

1. 检查 Registry 镜像源

国内开发者本地大多全局配置了淘宝镜像(Taobao/npmmirror)或公司内网源。第三方镜像源通常是只读镜像,无法直接写入,发布和登录必须切回 npm 官方源:

1
2
3
4
5
# 查看当前生效的镜像源
npm config get registry

# 临时或全局切回 npm 官方源
npm config set registry https://registry.npmjs.org/

💡 推荐工具:日常开发强烈建议安装 nrm(npm registry manager),多源一键平滑切换:

1
npx nrm use npm

2. 网络拦截与现代 2FA / WebAuthn 鉴权

在切回官方源后如果依然报 403 或网络超时,主要有两类根因:

  1. Cloudflare 拦截与跨国网络波动:在终端或浏览器访问 https://registry.npmjs.org/ 时,可能会遇到 Cloudflare 的高防拦截。此时需为终端配置代理环境变量:
    1
    2
    3
    # 为当前终端会话注入代理环境变量
    export http_proxy=http://127.0.0.1:7890
    export https_proxy=http://127.0.0.1:7890
  2. 现代 Web 登录流(WebAuthn):现代 npm CLI(Node.js >= 18)默认启用基于浏览器的双因素认证(2FA)。执行 npm login 时,终端会打印一个一次性配对口令并在浏览器中自动拉起登录授权页,通过硬件 Key 或验证码完成认证后,终端本地会安全生成带有效期的 Token。

二、现代构建与模块导出:攻克 ESM 与 CJS 双模块兼容

现代前端与 Node.js 社区最大的痛点之一,就是 CommonJS(CJS) 与 ECMAScript Modules(ESM) 的生态撕裂。一个设计良好的 npm 包应当做到让使用者无论是 import 还是 require 都能开箱即用,并且提供完备的 TypeScript .d.ts 类型定义。

1. 现代极速打包工具选择

推荐使用专门面向 TypeScript 库打包的现代构建工具(如 tsup),其底层基于 esbuild,零配置、构建速度比传统 tsc / webpack 快上百倍:

1
npm install -D tsup typescript

在 package.json 中配置打包脚本:

1
2
3
4
5
6
{
"scripts": {
"build": "tsup src/index.ts --format cjs,esm --dts --clean",
"prepublishOnly": "npm run test && npm run build"
}
}

该命令会自动生成:

  • dist/index.js(CJS 产物);
  • dist/index.mjs(ESM 产物);
  • dist/index.d.ts(TypeScript 类型声明文件)。

2. 标准化的 package.json 导出字段范式

不要仅停留在老旧的 main 字段上,现代包必须规范声明 exports 条件导出 与 files 白名单:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
"name": "@your-scope/awesome-lib",
"version": "1.0.0",
"description": "A high-performance modern TypeScript utility library",
"author": "Your Name <you@example.com>",
"license": "MIT",
"keywords": ["util", "typescript", "esm"],
"homepage": "https://github.com/your-name/awesome-lib#readme",
"repository": {
"type": "git",
"url": "git+https://github.com/your-name/awesome-lib.git"
},
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.js"
},
"./package.json": "./package.json"
},
"files": [
"dist",
"README.md",
"LICENSE"
],
"sideEffects": false
}

📌 核心避坑细节:

  1. exports 中的 types 顺序:types 必须放在 import 和 require 的最前面,否则 TypeScript 编译器解析时可能命中后面的 js 字段而忽略类型声明;
  2. sideEffects: false:声明该库无副作用,能够让 Webpack、Rollup、Vite 等上层打包工具进行彻底的 Tree-shaking(摇树优化);
  3. files 严格白名单:杜绝将 src/ 源码、本地测试用例、未忽略的 .env 敏感文件推到公网镜像。

三、版本管理:npm version 与 Git Tag 联动机制

发布开源包最忌讳的是 package.json 的版本号与 Git 仓库的 Commit、Tag 割裂脱节。手动修改文件、手动 git commit、再手动打 tag 极易出现人为遗漏。

npm 原生内置的 npm version 命令可以一键完成三件事:

  1. 更新 package.json(及 package-lock.json)的版本号;
  2. 自动生成一条版本变更的标准 Git Commit;
  3. 在本地 Git 仓库打上对应版本的 Git Tag。

1. 语义化版本更新命令

1
2
3
4
5
6
7
8
# 1. 修复 Bug (补丁版本自增:1.0.0 -> 1.0.1)
npm version patch -m "chore(release): bump version to %s"

# 2. 新增向下兼容的功能 (次版本自增:1.0.1 -> 1.1.0)
npm version minor -m "chore(release): bump version to %s"

# 3. 产生不向下兼容的重大破坏性改动 (主版本自增:1.1.0 -> 2.0.0)
npm version major -m "chore(release): bump version to %s"

其中 -m 参数用于定义 Commit Message,占位符 %s 会自动替换为带 v 前缀的新版本号(如 v1.0.1)。

2. 规范推送到远程仓库

打完 tag 后,不要盲目使用 git push origin --tags(这会把本地所有无关的测试 tag 全部推上去),推荐使用 --follow-tags:

1
2
# 只推送当前分支提交相关的带注释标签(Annotated Tags)
git push origin main --follow-tags

四、发包前防翻车:本地预演检验(Dry-Run)

在正式推送到云端前,建议通过以下两大法宝在本地进行 100% 仿真验货:

1
2
3
4
5
# 1. 模拟发包过程:打印即将被打包上传的完整文件树和体积,但不会实际发起网络请求
npm publish --dry-run

# 2. 在当前目录下生成一个标准的 .tgz 归档压缩包 (完全等同于 npm registry 上分发的内容)
npm pack

执行 npm pack 后,建议解压生成的 .tgz 文件,用肉眼检查:

  • dist/ 编译产物是否齐全且最新;
  • 是否混入了无关的临时缓存或测试文件;
  • 解压后的实际体积是否符合预期。

五、正式发包与 npm 严苛的撤包规则(Unpublish Policy)

确认无误后,执行正式发布:

1
2
3
4
5
# 普通无作用域包直接发布
npm publish

# 如果是 scoped 包 (如 @my-org/my-pkg),默认是私有包,公开发布必须声明 --access public
npm publish --access public

致命误区:切忌随意执行 npm unpublish

在此前的一次发包中,由于前序 Git Tag 与本地发包分支版本没有对齐,打出来的包配置与代码不一致。下意识想通过下述命令把刚刚发错的版本撤回并重新推送:

1
npm unpublish cherry-id@0.0.3 --force

然而,当切回正确的 Tag 试图重新发布 0.0.3 时,npm 控制台直接抛出严重错误:

1
2
npm ERR! 403 Forbidden - PUT https://registry.npmjs.org/cherry-id
npm ERR! You cannot publish over the previously published versions: 0.0.3.

并且提示:“同一个包名已被删除的版本,永久无法再次使用同名版本发布!”

npm 官方的“后悔药”限制规则(源自 left-pad 事件)

为了防止破坏全球 Node.js 社区的依赖树完整性(著名的 left-pad 下架导致全网构建瘫痪事件),npm 制定了极度严苛的撤包政策:

  1. 时间限制:只有发布后 24 小时以内 的包允许 unpublish;
  2. 依赖限制:如果该包已被任何其他公开包声明为依赖,禁止 unpublish;
  3. 版本黑名单机制(最关键):任何被删除过的版本号(如 0.0.3)将永远作废!你无法通过重新发布覆盖一个已经存在过或删除过的版本!

发错包的正确补救姿势

如果代码确实发错了,千万不要试图删除重发,标准的行业救砖方案为:

  1. 紧急发布新修复版本(Patch):直接修复代码并递增版本号发布新版本(如 0.0.4):

    1
    2
    npm version patch -m "fix: resolve packaging issue in v0.0.3"
    npm publish
  2. 弃用(Deprecate)问题版本:使用 npm deprecate 为发错的版本打上警告标记。用户安装该版本时会在终端看到醒目的黄色警示,引导其升级,但不会破坏依赖它的老项目构建:

    1
    npm deprecate cherry-id@0.0.3 "This version contains packaging defects, please upgrade to >= 0.0.4"

六、进阶:GitHub Actions 自动化 CI/CD 发包与 Provenance 签名

在现代化团队协作中,通常由 CI 机器人负责发包,彻底杜绝人为疏漏。

1. 配置自动化发包流水线

在仓库中创建 .github/workflows/publish.yml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
name: Publish to npm

on:
release:
types: [published]

jobs:
publish:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write # 用于生成 npm 官方安全来源凭证 (Provenance)
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
registry-url: 'https://registry.npmjs.org'

- run: npm ci
- run: npm run test
- run: npm run build

- name: Publish Package
run: npm publish --provenance --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

💡 什么是 --provenance? npm 官方推出的可信来源证明机制。带有该参数发布的包,在 npm 官网页面上会展示一个高颜值的绿色 Verified / Provenance 认证徽章,向全世界证明该软件包是直接在 GitHub Actions 公开流水线中从受保护的 Commit 构建出来的,不存在任何本地中间人篡改或恶意代码植入。


七、现代 npm 发包标准化 Checklist

为避免再次踩坑,发包前可遵循以下标准化自查清单:

1
2
3
4
5
6
7
8
9
10
11
[标准化发包自查清单]
[ ] 1. 检查源状态: npm config get registry -> 确保指向 https://registry.npmjs.org/
[ ] 2. 检查登录鉴权: npm whoami -> 确认当前登录账号正确
[ ] 3. 检查代码状态: git status -> 确保本地工作区无未提交的脏代码
[ ] 4. 检查打包清单: 确认 package.json 中 files 仅包含 dist/ 产物与必要文档
[ ] 5. 检查模块导出: 检查 exports 字段中 types 是否位于 import/require 之前
[ ] 6. 本地发布预演: 执行 npm pack 或 npm publish --dry-run 查看文件树
[ ] 7. 语义化自增: 执行 npm version <patch|minor|major> -m "..."
[ ] 8. 同步推送 Tag: git push origin --follow-tags
[ ] 9. 正式推送上线: npm publish (公共 scoped 包加 --access public)
[ ] 10. 如发错版本: 绝对不执行 unpublish,而是递增 patch 发布并对老版本 npm deprecate

参考与扩展阅读


npm 发包完整实践与避坑指南
https://bubao.github.io/posts/17f1901.html
作者
一念
发布于
2021年6月6日
许可协议