牧宇的Blog lihuanyu.com

GitHub Actions 自动发布 npm 包简易指南

前端

概述

GitHub Actions作为GitHub原生的CI/CD工具，为开发者提供了强大的自动化能力。通过GitHub Actions自动发布npm包，可以显著提升开发效率，减少人为错误，确保发布流程的一致性和可靠性。

本指南专注于简单实用的配置方案，特别适合：

  • 个人开发者的小型项目

  • 不需要复杂自动化流程的简单项目

  • 希望快速上手、配置简单的场景

  • 追求可靠性而非复杂功能的项目

相比复杂的语义化版本控制方案（如semantic-release），本方案采用手动版本管理，配置简单，维护成本低，非常适合个人项目使用。

基础配置

1. npm Token配置

首先需要在npm官网创建访问令牌：

  1. 登录 npmjs.com

  2. 进入 Access Tokens 页面

  3. 创建新的 Classic Token，类型选择 “Automation”

  4. 复制生成的token（注意！只显示一次）

在GitHub仓库中配置Secrets：

  1. 进入仓库 Settings → Secrets and variables → Actions

  2. 创建新的Repository secret

  3. Name: NPM_TOKEN，Value: 刚才复制的token

2. 基础工作流配置

创建 .github/workflows/npm-publish.yml 文件：

name: Publish NPM Package

on:
  push:
    tags:
      - 'v*'  # 当推送v开头的标签时触发

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org/'
      - run: npm ci
      - run: npm test # optional
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

简单发布流程

1. 手动版本管理

使用npm内置命令管理版本：

# 补丁版本 (1.0.0 -> 1.0.1)
npm version patch

# 次要版本 (1.0.0 -> 1.1.0)  
npm version minor

# 主要版本 (1.0.0 -> 2.0.0)
npm version major

2. 发布步骤

# 1. 更新版本号并创建标签
npm version patch

# 2. 推送代码和标签到GitHub
git push origin main --tags

# 3. GitHub Actions自动触发发布

安全最佳实践

1. Token安全管理

  • 使用Automation类型token：绕过2FA限制，专门用于CI/CD

  • 最小权限原则：只授予必要的发布权限

  • 定期轮换token：建议定期更新访问令牌

  • 环境变量隔离：只在npm publish步骤中暴露token

2. 工作流安全配置

permissions:
  contents: read
  packages: write

3. 分支保护策略

  • 限制对主分支的直接推送

  • 要求通过Pull Request进行代码审查

  • 启用状态检查，确保测试通过后才能合并

常见问题和解决方案

1. 版本冲突

  • 确保每次发布前版本号已更新

  • 检查npm上是否已存在相同版本

  • 使用 npm version 命令避免手动错误

2. 权限问题

  • 确保NPM_TOKEN具有发布权限

  • 检查包名是否已被占用

  • 验证组织权限设置

3. 构建失败

  • 添加完整的测试步骤

  • 确保依赖安装正确

  • 使用缓存优化构建速度

最佳实践总结

  1. 安全第一：妥善管理访问令牌，使用最小权限原则

  2. 简单可靠：使用标签触发，避免复杂的自动化逻辑

  3. 测试保障：发布前确保所有测试通过

  4. 版本管理：使用npm内置版本管理命令

  5. 监控告警：设置基本的失败检测

pnpm版本配置

对于使用pnpm的项目，可以使用以下配置：

name: Publish NPM Package (pnpm)

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org/'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm test # optional
      - run: pnpm publish --no-git-checks
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

pnpm配置要点：

  • 使用 pnpm/action-setup@v2 安装pnpm

  • 使用 cache: 'pnpm' 启用pnpm缓存

  • 使用 pnpm install --frozen-lockfile 确保依赖一致性

  • 使用 pnpm publish --no-git-checks 发布包

注意事项

package.json配置检查

发布前请确保package.json配置正确：

  1. 移除private字段：如果存在 "private": true，必须删除或设为 false
{
    "name": "your-package-name",
    "version": "1.0.0",
    // "private": true,  ← 删除这行，注意json不支持注释，必须删除
    "description": "Your package description"
}

  1. 确保包名可用：检查npm上是否已存在同名包

  2. 设置正确的入口文件：确保 main 字段指向正确的文件

{
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}