17.3 发布到 npm

17.3 发布到 npm

将你的 JavaScript 工具库发布到 npm 是分享给全球开发者的重要步骤。本节将详细介绍从准备到发布的完整流程，包含现代最佳实践和常见问题解决方案。

发布前的准备工作

1. 确保合理的项目结构

your-library/
├── dist/               # 打包后的文件（必须包含）
├── src/                # 源代码
├── __tests__/          # 测试文件
├── package.json        # 核心配置文件
├── README.md           # 项目文档
├── CHANGELOG.md        # 变更日志（可选但推荐）
└── LICENSE             # 开源协议（必须）

2. 关键 package.json 配置

{
  "name": "your-library-name",
  "version": "1.0.0",
  "description": "清晰的库描述",
  "main": "dist/bundle.cjs.js",        // CommonJS 入口
  "module": "dist/bundle.esm.js",      // ES Module 入口
  "types": "dist/types/index.d.ts",    // TypeScript 类型声明
  "files": ["dist"],                   // 包含发布的文件
  "keywords": ["your", "keywords"],    // 搜索关键词
  "license": "MIT",
  "scripts": {
    "prepublishOnly": "npm run build && npm test",
    "prepare": "npm run build"
  },
  "peerDependencies": {                // 配套依赖
    "react": ">=16.8.0"
  },
  "publishConfig": {
    "access": "public",                // 公开包
    "registry": "https://registry.npmjs.org/"
  }
}

发布流程详解

1. 注册 npm 账号

npm adduser
# 或使用现有账号登录
npm login

2. 版本管理规范（遵循语义化版本）

npm version patch  # 1.0.0 → 1.0.1（小修复）
npm version minor  # 1.0.1 → 1.1.0（新增功能）
npm version major  # 1.1.0 → 2.0.0（重大变更）

3. 实际发布命令

npm publish

4. 发布测试包（推荐首次发布时使用）

npm publish --tag beta
# 用户安装时需指定版本
npm install your-library@beta

高级发布策略

1. 多环境发布配置

"publishConfig": {
  "access": "public",
  "tag": "latest",
  "registry": "https://registry.npmjs.org/"
}

2. 使用 np 工具（更安全的发布）

npx np

3. 自动化发布流程（GitHub Actions 示例）

name: Publish
on:
  release:
    types: [created]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '14'
      - run: npm ci
      - run: npm test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

发布后的重要维护工作

1. 版本撤回（仅限72小时内）

npm unpublish [email protected]

2. 废弃版本

npm deprecate [email protected] "这个版本存在安全问题，请升级到1.0.1"

3. 添加版本标签

npm dist-tag add [email protected] latest

现代工具库的最佳实践

1. 双模式打包（CJS + ESM）

{
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "exports": {
    ".": {
      "require": "./dist/cjs/index.js",
      "import": "./dist/esm/index.js"
    },
    "./features/*": {
      "require": "./dist/cjs/features/*.js",
      "import": "./dist/esm/features/*.js"
    }
  }
}

2. TypeScript 支持

1. 生成声明文件：

{
  "types": "dist/types/index.d.ts",
  "scripts": {
    "build:types": "tsc --emitDeclarationOnly --outDir dist/types"
  }
}

2. 类型导出示例：

// src/types.ts
export interface Config {
  timeout?: number;
  retry?: boolean;
}

// 在入口文件导出
export * from './types';

3. 浏览器直接引入支持

{
  "unpkg": "dist/umd/your-library.min.js",
  "jsdelivr": "dist/umd/your-library.min.js"
}

常见问题解决方案

1. 403 发布错误

• 问题：包名已被占用
• 解决：

  npm view your-library-name
  # 如果存在，修改 package.json 中的 name
  
  

2. 402 付费错误

• 问题：尝试发布私有包但未付费
• 解决：

  npm publish --access public
  

3. 版本冲突

• 问题：本地版本低于 npm 上的版本
• 解决：

  npm version major -f
  

安全注意事项

1. 永远不要发布敏感信息：

   • 检查 .npmignore 或 files 字段
   • 确保不包含 .env、config.json 等文件

2. 双重认证：

   npm profile enable-2fa
   

3. Token 管理：

   npm token create --read-only
   

发布检查清单

在发布前确保：

• [ ] 所有测试通过 (npm test)
• [ ] 版本号已更新
• [ ] README 文档完整
• [ ] 构建产物是最新的 (npm run build)
• [ ] 类型定义文件已生成（如适用）
• [ ] 检查过 .npmignore 或 files 字段
• [ ] 开源协议已添加

自动化发布工作流推荐

1. 使用 release-it：

   npx release-it
   

2. 配置示例：

   {
     "scripts": {
       "release": "release-it"
     },
     "release-it": {
       "git": {
         "commitMessage": "chore: release v${version}",
         "tagName": "v${version}"
       },
       "npm": {
         "publish": true
       },
       "github": {
         "release": true
       }
     }
   }
   

通过以上步骤，你已经掌握了专业级的 npm 发布流程。记住发布只是开始，持续的版本更新和维护才是关键。接下来我们将进入项目实战的第二部分 - 单页应用开发。