npm-publish

npm 自动发布配置指南

将 npm 包通过 GitHub Actions + OIDC Trusted Publishing 自动发布，无需管理 npm token。

核心知识

Node 版本要求

OIDC Trusted Publishing 需要 npm CLI >= 11.5.1。各 Node 版本对应的 npm：

Node 版本	npm 版本	是否支持 Trusted Publishing
Node 20	npm 10.x	不支持
Node 22	npm 10.9.x	不支持
Node 24	npm 11.x+	支持

必须使用 Node 24，这是最常见的失败原因。

Private 仓库限制

--provenance 签名仅支持 public 仓库。Private 仓库使用 --provenance 会报错：

Error verifying sigstore provenance bundle: Unsupported GitHub Actions source repository visibility: "private"

Private 仓库需要去掉 --provenance flag。

配置流程

第一步：确认 package.json 配置

确保 package.json 包含以下关键字段：

{
  "name": "@scope/package-name",
  "version": "1.0.0",
  "files": ["dist", "README.md"],
  "publishConfig": {
    "access": "public"
  }
}

• scoped 包（@xxx/yyy）需要 publishConfig.access: "public"，否则默认 restricted
• files 字段控制发布内容，避免发布 src、node_modules 等

第二步：创建 GitHub Actions Workflow

创建 .github/workflows/publish.yml：

Public 仓库（推荐，带 provenance）：

name: Publish to npm

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: npm
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org

      - run: npm ci
      - run: npm run build
      - run: npm publish --provenance --access public

Private 仓库（不带 provenance）：

name: Publish to npm

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: npm
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org

      - run: npm ci
      - run: npm run build
      - run: npm publish --access public