Git Actions 通用 npm 包自动发布实践

原创

除除

修改于 2025-09-28 16:27:57

1690

文章被收录于专栏：除除的专栏除除的专栏

声明：

本文仅用于技术分享和学习交流，内容不包含任何广告、推广、引流、付费课程或外链信息。所有示例和配置均为技术实践，欢迎参考和自定义。

自动化发布 npm 包是现代前端和 Node.js 开发的标配。本文将介绍两种常用的发布流程，这两套 Workflow 都可直接复用，适合绝大多数 npm 包项目的自动化集成。

版本 1: 发布到 npm

适合绝大多数 npm 包场景。此 Workflow 只发布到 npmjs.org，配置简单，安全高效。

流程说明

配置 NPM_TOKEN: Git → Settings → Secrets and variables → Actions → Repository secrets。
流程清晰: 测试 → 构建 → 发布 npm → 打 Tag。

.github/workflows/publish-npm.yml:

name: Publish npm Packages

env:
  NODE_VERSION: '20'

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Install dependencies
        run: npm install

      - name: Build package
        run: npm run build --if-present

      - name: Run tests
        run: npm test

  publish:
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name == 'push'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          registry-url: 'https://registry.npmjs.org/'

      - name: Install dependencies
        run: npm install

      - name: Build package
        run: npm run build --if-present

      - name: Publish to npm
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npm publish --access public

      - name: Create git tag for version
        if: success()
        run: |
          VERSION=$(node -p "require('./package.json').version")
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git tag -a "v$VERSION" -m "Release v$VERSION"
          git push origin "v$VERSION"

版本 2: 同时发布到 npm 和 Git Packages

将包同步分发到 Git Packages，可用下述 Workflow。对比版本 1，新增了 Git Packages 配置。

流程说明

Git Packages 需要额外配置 .npmrc 和包名 (如 @user/project)。
发布前需确保有 GITHUB_TOKEN (Git Actions 默认提供无需设置)。
使用脚本 scripts/change-package-name.js 自动切换包名。

scripts/change-package-name.js:

const fs = require('fs');

const newName = process.argv[2];
if (!newName) {
  console.error('Error: New name argument is required.');
  process.exit(1);
}

const pkgPath = 'package.json';
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
pkg.name = newName;
fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
console.log(`package.json name changed to "${newName}"`);

.github/workflows/publish-npm.yml:

name: Publish npm Packages

env:
  NODE_VERSION: '20'
  PROJECT_NAME: 'mazey-npm-template'

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Install dependencies
        run: npm install

      - name: Build package
        run: npm run build --if-present

      - name: Run tests
        run: npm test

  publish:
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name == 'push'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          registry-url: 'https://registry.npmjs.org/'

      - name: Install dependencies
        run: npm install

      - name: Build package
        run: npm run build --if-present

      - name: Publish to npm
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npm publish --access public

      - name: Configure .npmrc for Git Packages
        run: |
          echo "@${{ github.actor }}:registry=https://npm.pkg.github.com/" > .npmrc
          echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" >> .npmrc

      - name: Publish to Git Packages
        if: success()
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          node scripts/change-package-name.js "@${{ github.actor }}/${{ env.PROJECT_NAME }}"
          npm publish --registry=https://npm.pkg.github.com/

      - name: Restore modified files
        if: always()
        run: git checkout -- package.json .npmrc

      - name: Create git tag for version
        if: success()
        run: |
          VERSION=$(node -p "require('./package.json').version")
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git tag -a "v$VERSION" -m "Release v$VERSION"
          git push origin "v$VERSION"

分支命名示例

1. 只监听主分支 main:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

2. 监听所有以 release/v 开头的分支 (如 release/v1.0.0、release/v2.1.3 等):

on:
  push:
    branches:
      - 'release/v*'
  pull_request:
    branches:
      - 'release/v*'

建议:

main: 对于仅用于主干发布的项目，直接监听 main 即可。
release/v*: 带有版本号的格式 (如 release/v1.2.3)。这种命名方式相对清晰，能标识每次发布的具体版本号，同时也便于自动化脚本或 CI 流程处理不同版本的发布。

注意:

含有 * 的分支名建议加单引号，避免 YAML 解析异常。
只有被 branches 匹配到的分支推送 (push) 或拉取请求 (pull_request) 会触发 Workflow。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

git-branch

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

登录后参与评论

0 条评论

热度