实践github actions完成项目的打包&发布
概述
本节实操 GitHub Actions 工作流配置，完成从本地准备、YAML 编写到线上发布的完整流程，包括 Node 版本管理、依赖锁定和发布策略。
发布前准备工作
1. 本地构建验证
# 确保本地构建通过
npm run compile
# 运行 ESLint 检查
npm run lint
# 运行 TypeScript 类型检查
npm run type-check
# 代码格式化
npx lint-staged
bash
| 检查项 | 命令 | 作用 |
|---|---|---|
| 构建 | npm run compile | 验证代码可正常构建 |
| Lint | npm run lint | 检查代码风格问题 |
| 类型检查 | npm run type-check | TypeScript 类型安全 |
| 格式化 | lint-staged | 统一代码风格 |
2. 生成 package-lock.json
# 使用指定 Node 版本
nvm use v16
# 只生成 lock 文件，不安装依赖
npm install --package-lock-only
bash
关键：
--package-lock-only只生成 lock 文件，确保 CI 环境安装的依赖版本与本地一致。
3. 配置 Husky（可选）
# 安装 husky
npx husky install
# 添加 pre-commit hook
npx husky add .husky/pre-commit "npm run lint"
npx husky add .husky/pre-commit "npm run type-check"
bash
GitHub Actions 工作流配置
完整的发布工作流
# .github/workflows/publish.yml
name: Build and Publish
on:
push:
branches: [main]
tags: ['v*']
workflow_dispatch: # 手动触发
jobs:
# === 代码质量检查 ===
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
- run: npm ci
- run: npm run lint
- run: npm run type-check
# === 构建与测试 ===
build:
needs: lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
- run: npm ci
- run: npm run compile
- name: Upload build artifacts
uses: actions/upload-artifact@v4
with:
name: dist
path: dist/
# === 发布到 npm ===
publish:
needs: build
runs-on: ubuntu-latest
if: startsWith(github.ref, 'refs/tags/v')
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '18'
registry-url: 'https://registry.npmjs.org'
- name: Download build artifacts
uses: actions/download-artifact@v4
with:
name: dist
path: dist/
- run: npm publish --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
# === 创建 GitHub Release ===
release:
needs: build
runs-on: ubuntu-latest
if: startsWith(github.ref, 'refs/tags/v')
steps:
- uses: actions/checkout@v4
- name: Download build artifacts
uses: actions/download-artifact@v4
with:
name: dist
path: dist/
- name: Create Release
uses: softprops/action-gh-release@v2
with:
generate_release_notes: true # 自动生成 release note
files: |
dist/**
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
yaml
macOS 平台特殊配置
# macOS 构建需要特别注意证书和签名
build-mac:
runs-on: macos-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '18'
# macOS 证书配置（如需签名）
- name: Import Certificate
env:
CERTIFICATE_BASE64: ${{ secrets.MAC_CERTIFICATE }}
CERTIFICATE_PASSWORD: ${{ secrets.MAC_CERT_PASSWORD }}
run: |
echo "$CERTIFICATE_BASE64" | base64 --decode > certificate.p12
security create-keychain -p actions temp.keychain
security import certificate.p12 -k temp.keychain -P "$CERTIFICATE_PASSWORD"
security list-keychains -s temp.keychain
- run: npm ci
- run: npm run build -- --mac
yaml
Secrets 配置
在 GitHub 仓库的 Settings → Secrets and variables → Actions 中配置：
| Secret 名称 | 用途 | 获取方式 |
|---|---|---|
NPM_TOKEN | npm 发布认证 | npmjs.com → Access Tokens |
GITHUB_TOKEN | GitHub Release | 自动提供，无需配置 |
MAC_CERTIFICATE | macOS 签名证书 | Base64 编码的 .p12 文件 |
MAC_CERT_PASSWORD | 证书密码 | 导出证书时设置的密码 |
发布流程操作
# 1. 确保代码已提交
git add .
git commit -m "feat: prepare for release"
# 2. 更新版本号
npm version patch # 或 minor / major
# 3. 推送代码和 tag
git push origin main --tags
# 4. GitHub Actions 自动执行：
# lint → build → publish (npm) + release (GitHub)
bash
手动触发与 Release Note
# 添加手动触发支持
on:
workflow_dispatch: # 在 Actions 面板手动点击运行
inputs:
version:
description: '发布版本号'
required: true
yaml
Release Note 自动从 commit 历史生成，也可在 build settings 中自定义。
小结
- 发布前必须本地验证构建、lint 和类型检查
- 使用
--package-lock-only确保 CI 环境依赖一致性 - 工作流分为 lint → build → publish/release 三个阶段
- macOS 平台需要额外配置证书签名
- 支持
workflow_dispatch手动触发和自动生成 Release Note
↑