背景

手动发布 npm 包需要本地执行 npm publish，每次都要确保版本号更新、构建完成，且需要配置 npm token。使用 GitHub Actions 可以实现自动化发布，代码推送到 main 分支后自动构建并发布到 npm。

配置

在 .github/workflows/publish.yml 创建以下配置：

name: Publish Package

on:
  push:
    branches: [main]

permissions:
  id-token: write  # Required for OIDC
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 8.6.2

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
          cache: "pnpm"

      # Ensure npm 11.5.1 or later is installed
      - name: Update npm
        run: npm install -g npm@latest

      - run: pnpm install --no-frozen-lockfile
      - run: npm run build 
      - run: npm publish  --access public

关键配置说明

OIDC 认证

id-token: write 权限启用 OIDC（OpenID Connect）认证，无需在 GitHub Secrets 中存储 npm token。actions/setup-node@v4 会自动使用 OIDC token 进行 npm 认证。

npm 版本更新

npm 11.5.1+ 版本才支持 OIDC，因此需要先更新 npm 到最新版本。

发布参数

  • --access public: 发布公开包（scoped package 默认是 private）
  • --no-frozen-lockfile: 允许更新 lockfile，适用于 CI 环境

前置条件

  1. npm 账号配置

    • 在 npm 账号设置中启用 “Automation tokens”
    • 确保包名在 npm 上可用

  2. package.json 配置

    {
  "name": "your-package-name",
  "version": "1.0.0",
  "scripts": {
    "build": "your-build-command"
  }
}

  3. 首次发布

    • 首次发布需要手动执行一次 npm publish 建立包
    • 或确保包名未被占用

工作流程

  1. 代码推送到 main 分支
  2. GitHub Actions 自动触发
  3. 安装依赖并构建项目
  4. 自动发布到 npm（版本号需在 package.json 中手动更新）

注意事项

  • 版本号需要在 package.json 中手动更新，或使用 npm version 命令
  • 确保 build 脚本能正常执行
  • 首次使用 OIDC 需要在 npm 账号中启用自动化 token
  • 如果发布失败，检查 npm 账号权限和包名是否正确