发布 npm 包完整指南（含账号注册、发布撤销与注意事项）
发布一个 npm 包，可以让你分享自己的工具库、组件库、脚手架等给全世界或团队内部使用。本文将带你从 0 到 1 完成一个 npm 包的发布流程，包括账号注册、版本控制、发布命令，以及撤回方法和实用建议。
🧰 发布前准备
在发布前，请确保你具备以下环境和账号：
- ✅ 安装了 Node.js（推荐 LTS 版本）
- ✅ 已切换至 npm 官方源（默认即是）
- ✅ 拥有一个 npm 账号
# 确保使用官方源（默认一般已经是）
npm config set registry https://registry.npmjs.org/
🧾 一、注册 npm 账号（推荐使用网页注册）
npm 官方推荐使用网页方式进行注册，并完成邮箱验证。
✅ 网页注册步骤：
- 打开 https://www.npmjs.com/signup
- 输入用户名、邮箱、密码
- 通过邮箱验证，注册完成
❌
npm adduser虽然也可以尝试注册新账号，但经常因未验证邮箱而导致发布失败，不推荐！
🔐 二、登录 npm 账号
注册成功后，在命令行中登录你的 npm 账号：
npm login
依次输入：
- Username
- Password
- Email（用于接收验证和通知）
如果你使用了组织作用域（如 @your-org/xxx），确保你登录的是该组织有权限的账号。
🏗️ 三、准备并配置你的包
1. 初始化项目
mkdir my-utils && cd my-utils
npm init -y
2. 修改 package.json
{"name": "@your-scope/utils", // 建议使用 scoped 包名（避免全局冲突）"version": "1.0.0","description": "A useful utility library","main": "dist/index.js", // 构建输出主入口"types": "dist/index.d.ts", // TypeScript 类型声明"files": ["dist"], // 指定发布哪些文件夹"author": "aiyvyang","license": "MIT","repository": {"type": "git","url": "https://github.com/yourname/utils.git"}
}
3. 构建输出文件
使用 tsup、vite 或 rollup 等构建工具：
pnpm add -D tsup typescript
npx tsup src/index.ts --format esm,cjs --dts
✅ 确保
dist/中包含构建后的 JS 和 d.ts 文件
🚀 四、发布包到 npm
1. 每次发布都必须更新版本号
遵循 Semver 语义化版本号 规范：
| 类型 | 示例 | 说明 |
|---|---|---|
| Patch 修复 | 1.0.0 → 1.0.1 | 修复 bug，不影响 API |
| Minor 新增 | 1.0.0 → 1.1.0 | 新功能，无破坏性 |
| Major 破坏 | 1.0.0 → 2.0.0 | 有破坏性改动 |
2. 发布命令（scoped 包需声明公开访问）
npm publish --access public
📌 若不加
--access public，scoped 包默认是私有的，非企业账户将报错 402
🛑 五、撤销已发布的包（24 小时内有效）
1. 撤销整个包（慎用）
npm unpublish your-package-name --force
🚨 警告：慎用
--force，一旦撤销整个包名，未来不能再使用！
2. 撤销指定版本（推荐）
npm unpublish your-package-name@1.0.0
📌 常见问题与发布建议
| 问题 | 原因/解决方式 |
|---|---|
403 Forbidden | 包名已存在 / 没有权限 → 换包名或确认是否你是原作者 |
402 Payment Required | scoped 包默认私有 → 添加 --access public |
Cannot publish over version | 当前版本已存在 → 更新 version 字段（不可覆盖旧版本） |
| 发布后未生效 | 忘记构建或未包含构建文件 → 确保 dist 文件夹存在 & files 字段设置正确 |
⚙️ Bonus：配置自动发布（GitHub Actions）
可以使用 GitHub Actions 实现打 tag 自动发布 npm 包：
# .github/workflows/release.yml
name: Releaseon:push:tags:- 'v*'jobs:release:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- uses: actions/setup-node@v3with:node-version: 20registry-url: 'https://registry.npmjs.org/'- run: npm install- run: npm run build- run: npm publish --access publicenv:NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
在仓库设置里添加 NPM_TOKEN，生成方法见：npm access tokens
✅ 总结
发布 npm 包的流程并不复杂，但关键是「规范 + 自动化」：
- ✅ 官网注册账号 + 命令行登录
- ✅ 使用 scoped 包名防止冲突
- ✅ 遵循语义化版本发布
- ✅ 配合构建工具输出生产可用代码
- ✅ 可接入 GitHub Actions 自动发布