发布 npm 包完整指南（含账号注册、发布撤销与注意事项）

发布一个 npm 包，可以让你分享自己的工具库、组件库、脚手架等给全世界或团队内部使用。本文将带你从 0 到 1 完成一个 npm 包的发布流程，包括账号注册、版本控制、发布命令，以及撤回方法和实用建议。

---

发布前准备

在发布前，请确保你具备以下环境和账号：

• ✅ 安装了 Node.js（推荐 LTS 版本）
• ✅ 已切换至 npm 官方源（默认即是）
• ✅ 拥有一个 npm 账号

# 确保使用官方源（默认一般已经是）
npm config set registry https://registry.npmjs.org/

---

一、注册 npm 账号（推荐使用网页注册）

npm 官方推荐使用网页方式进行注册，并完成邮箱验证。

✅ 网页注册步骤：

1. 打开 https://www.npmjs.com/signup
2. 输入用户名、邮箱、密码
3. 通过邮箱验证，注册完成

❌ 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 [email protected]

---

常见问题与发布建议

问题	原因/解决方式
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 自动发布