npm 包发布流程

npm 包发布流程

一、前置准备

1. 注册/登录 npm 账号

• 前往 npm 官网 注册账号（需验证邮箱，未验证无法发布）。

• 本地终端登录账号（确保 npm 源是官方源，而非淘宝镜像等）：

  # 检查 npm 源（非官方源需切换）
  npm config get registry
  # 切换为官方源
  npm config set registry https://registry.npmjs.org/
  # 登录账号（按提示输入用户名、密码、邮箱）
  npm login

  登录成功后可通过 npm whoami 验证当前登录用户。

2. 环境与工具准备

• 确保安装 Node.js（建议 LTS 版本）和 npm（或 yarn/pnpm，流程通用）。
• 可选：安装 np（简化发布流程的工具）、semver（版本号校验）等辅助包。

二、包项目初始化与配置

1. 初始化项目（新建包）

# 创建项目目录并进入
mkdir my-npm-package && cd my-npm-package
# 初始化 package.json（按提示填写，或 -y 快速生成）
npm init [-y]

2. 核心配置：package.json 关键字段

package.json 是 npm 包的核心配置文件，需重点配置以下字段：

字段	说明	示例
name	包名（必填，需唯一，小写/连字符，可带@scope）	"name": "my-utils" 或 "@username/my-utils"（私有域）
version	版本号（必填，遵循 SemVer 语义化版本：主版本.次版本.补丁）	"version": "1.0.0"
description	包描述（便于搜索）	"description": "常用工具函数集合"
main	入口文件（默认 index.js）	"main": "dist/index.js"（打包后入口）
files	指定发布时包含的文件/目录（避免发布无关文件）	"files": ["dist", "README.md"]
scripts	自定义脚本（如构建、测试）	"scripts": { "build": "tsc", "test": "jest" }
keywords	关键词（便于 npm 搜索）	"keywords": ["utils", "tool", "javascript"]
author	作者信息	"author": "YourName <your@email.com>"
license	开源协议（必填，如 MIT）	"license": "MIT"
repository	代码仓库地址	"repository": { "type": "git", "url": "git+https://github.com/xxx/my-utils.git" }
bugs	问题反馈地址	"bugs": { "url": "https://github.com/xxx/my-utils/issues" }
homepage	包主页（如 GitHub README）	"homepage": "https://github.com/xxx/my-utils#readme"
private	是否私有（true 则无法发布）	"private": false（必须为 false）

3. 其他关键文件

• README.md：必填，说明包的功能、安装、使用示例、API、注意事项等（提升易用性）。

• .npmignore ：排除发布文件（优先级低于 files 字段），如：

  # 排除目录
  node_modules/
  src/
  test/
  # 排除文件
  .gitignore
  .env
  *.log

• LICENSE ：开源协议文件（如 MIT 协议，可从 choosealicense.com 生成）。

三、本地测试（避免发布后踩坑）

1. 本地链接测试

通过 npm link 将包链接到全局，再在测试项目中链接使用：

# 在包目录执行（链接到全局）
npm link
# 新建测试项目，进入后执行（链接到本地包）
npm link my-utils
# 测试项目中引入包，验证功能是否正常

2. 代码校验与测试

• 执行单元测试（如 jest、mocha）：npm run test。
• 代码规范校验（如 eslint）：npm run lint。
• 若使用 TypeScript，确保编译成功：npm run build。

四、发布上线

1. 基础发布（公开包）

# 检查 package.json 配置（可选）
npm pkg verify
# 发布包（默认公开）
npm publish

2. 发布作用域包（@username/xxx）

• 公开的作用域包：

  npm publish --access public

• 私有作用域包（需 npm 付费账号）：

  npm publish --access private

3. 发布测试版本（预发布）

# 发布 beta 版本（如 1.0.0-beta.1）
npm version prerelease --preid=beta
npm publish --tag beta
# 安装测试版本：npm install my-utils@beta

五、版本维护与更新

1. 更新版本号（SemVer 规范）

# 补丁版本（修复 bug，如 1.0.0 → 1.0.1）
npm version patch
# 次版本（新增功能，如 1.0.1 → 1.1.0）
npm version minor
# 主版本（不兼容更新，如 1.1.0 → 2.0.0）
npm version major

2. 发布更新版本

版本号更新后，重新执行发布命令：

npm publish

3. 撤销发布（谨慎使用）

若发布后发现严重问题，可撤销发布（仅限发布后 24 小时内，且无依赖）：

# 撤销整个版本
npm unpublish my-utils@1.0.0 --force
# 或弃用版本（更推荐，保留版本但标记为弃用）
npm deprecate my-utils@1.0.0 "该版本存在 bug，请升级至 1.0.1"

六、常见问题与注意事项

1. 403 错误：账号未验证邮箱、包名已被占用、无私有包权限。
2. 401 错误 ：未登录或登录状态过期，重新执行 npm login。
3. 源问题 ：确保发布时使用 npm 官方源，发布后可切回淘宝源：npm config set registry https://registry.npmmirror.com/。
4. 文件缺失 ：检查 files 字段或 .npmignore，确保打包后的文件被包含。
5. 版本号重复：已发布的版本号无法重复发布，需更新版本号。

七、进阶优化（可选）

• 使用 np 工具简化发布流程（自动校验、版本更新、发布）：

  npm install -g np
  np # 交互式发布

• 使用 GitHub Actions 实现自动化发布（提交代码/打 Tag 自动发布）。

• 配置 publishConfig 字段（如固定 registry）：

  "publishConfig": {
    "registry": "https://registry.npmjs.org/"
  }