发布一个 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: Release
on:
push:
tags:
- 'v*'
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 20
registry-url: 'https://registry.npmjs.org/'
- run: npm install
- run: npm run build
- run: npm publish --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
在仓库设置里添加 NPM_TOKEN，生成方法见：npm access tokens
✅ 总结
发布 npm 包的流程并不复杂，但关键是「规范 + 自动化」：
- ✅ 官网注册账号 + 命令行登录
- ✅ 使用 scoped 包名防止冲突
- ✅ 遵循语义化版本发布
- ✅ 配合构建工具输出生产可用代码
- ✅ 可接入 GitHub Actions 自动发布