Skip to content

Latest commit

 

History

History
397 lines (292 loc) · 7.91 KB

setup-guide.md

File metadata and controls

397 lines (292 loc) · 7.91 KB

🚀 GitHub Actions 自动化部署指南

本指南将帮助你设置完整的 GitHub Actions 自动化工作流，实现代码提交即自动发布的流程。

📋 目录

🚀 快速开始

1. 复制工作流文件

将以下文件复制到你的项目中：

# 创建 GitHub Actions 目录
mkdir -p .github/workflows

# 复制工作流文件
cp docs/templates/github/workflows/release.template.yml .github/workflows/release.yml
cp docs/templates/github/workflows/ci.template.yml .github/workflows/ci.yml

2. 配置 NPM Token

  1. 获取 NPM Token

    # 登录 NPM
npm login

# 或者访问 https://www.npmjs.com/
# 点击头像 -> Access Tokens -> Generate New Token
# 选择 "Automation" 类型

  2. 设置 GitHub Secrets

    • 访问你的 GitHub 仓库
    • 点击 Settings -> Secrets and variables -> Actions
    • 点击 New repository secret
    • 名称: NPM_TOKEN
    • 值: 你的 NPM token

3. 更新 package.json

确保你的 package.json 包含必要的脚本：

{
  "scripts": {
    "build": "tsc",
    "test": "jest",
    "test:coverage": "jest --coverage",
    "lint": "eslint src/**/*.ts",
    "type-check": "tsc --noEmit"
  }
}

🔧 环境配置

必需的 Secrets

在 GitHub 仓库设置中配置以下 Secrets：

Secret 名称 描述 获取方式
NPM_TOKEN NPM 发布令牌 npmjs.com -> Access Tokens
GITHUB_TOKEN GitHub API 令牌 自动提供，无需配置

可选的 Secrets

Secret 名称 描述 用途
SLACK_WEBHOOK Slack 通知 发布通知
DISCORD_WEBHOOK Discord 通知 发布通知

NPM Token 详细获取步骤

  1. 登录 NPM 官网

  2. 创建访问令牌

    点击头像 -> Access Tokens -> Generate New Token

  3. 选择令牌类型

    • Classic Token: 选择 "Automation"
    • Granular Access Token: 选择相应的包权限

  4. 复制令牌

    • ⚠️ 令牌只显示一次，请立即复制保存

  5. 添加到 GitHub Secrets

    仓库 -> Settings -> Secrets and variables -> Actions -> New repository secret
Name: NPM_TOKEN
Secret: 你的令牌

📖 工作流说明

🔄 CI 工作流 (ci.yml)

触发条件:

  • Push 到 main/master/develop 分支
  • Pull Request 到 main/master 分支

检查内容:

  • 🧪 多平台多版本测试 (Ubuntu/Windows/macOS + Node 18/20/21)
  • 🔐 安全扫描和漏洞检查
  • 📦 依赖状态检查
  • ⚡ 性能和包大小测试
  • 🔄 多包管理器兼容性 (npm/yarn/pnpm)
  • 📚 文档完整性检查

🚀 发布工作流 (release.yml)

触发条件:

  • Push 带有 v* 标签 (如 v1.0.0)
  • Push 到 main/master 分支且提交信息包含特定关键词

发布流程:

  1. 代码质量检查
  2. 构建项目
  3. 发布到 NPM
  4. 创建 GitHub Release
  5. 自动版本管理

🎯 使用方法

方法一：自动版本管理 (推荐)

使用规范化的提交信息，系统会自动判断版本类型：

# 新功能 (minor 版本升级)
git commit -m "feat: 添加新的数据处理功能"

# 修复 (patch 版本升级)  
git commit -m "fix: 修复参数解析错误"

# 破坏性更改 (major 版本升级)
git commit -m "breaking: 重构 API 接口"

# 强制发布
git commit -m "[release] 发布新版本"

# 推送到主分支
git push origin main

提交信息约定:

  • feat: 新功能 → minor 版本 (1.0.0 → 1.1.0)
  • fix: 修复 → patch 版本 (1.0.0 → 1.0.1)
  • breaking: 破坏性更改 → major 版本 (1.0.0 → 2.0.0)
  • [release] 强制发布 → patch 版本

方法二：手动版本管理

# 手动创建版本标签
git tag v1.2.0

# 推送标签触发发布
git push origin v1.2.0

方法三：npm version 命令

# 升级 patch 版本
npm version patch

# 升级 minor 版本  
npm version minor

# 升级 major 版本
npm version major

# 推送标签
git push --follow-tags

🔍 发布状态检查

查看工作流状态

  1. GitHub Actions 页面

    仓库 -> Actions -> 查看运行状态

  2. 发布状态检查

    # 检查 NPM 包状态
npm info your-package-name

# 检查最新版本
npm view your-package-name version

  3. GitHub Release 检查

    仓库 -> Releases -> 查看发布记录

🛠️ 故障排除

常见问题

1. NPM 发布失败

错误: npm ERR! 403 Forbidden

解决方案:

# 检查 NPM Token 权限
npm whoami

# 重新生成 Token
# 确保选择 "Automation" 类型
# 更新 GitHub Secrets

2. 版本冲突

错误: npm ERR! You cannot publish over the previously published versions

解决方案:

# 检查当前版本
npm view your-package-name version

# 手动升级版本
npm version patch

# 重新推送
git push --follow-tags

3. 构建失败

错误: npm run build 失败

解决方案:

# 本地测试构建
npm run build

# 检查 TypeScript 配置
npx tsc --noEmit

# 检查依赖
npm audit fix

4. 测试失败

错误: 测试用例未通过

解决方案:

# 本地运行测试
npm test

# 更新测试快照
npm test -- --updateSnapshot

# 检查测试覆盖率
npm run test:coverage

调试技巧

  1. 查看详细日志

    GitHub Actions -> 点击失败的工作流 -> 查看详细步骤

  2. 本地模拟 CI 环境

    # 使用相同的 Node 版本
nvm use 20

# 清理安装
rm -rf node_modules package-lock.json
npm ci

# 运行所有检查
npm run lint
npm run type-check  
npm run build
npm test

  3. 检查 package.json 配置

    {
  "files": [
    "dist/**/*",
    "README.md",
    "LICENSE"
  ],
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "bin": {
    "your-cli": "dist/cli.js"
  }
}

✨ 最佳实践

1. 提交信息规范

使用 Conventional Commits 规范：

# 格式: <type>[optional scope]: <description>

feat: 添加新功能
fix: 修复 bug
docs: 更新文档
style: 代码格式调整
refactor: 重构代码
test: 添加测试
chore: 构建过程或辅助工具的变动

2. 版本管理策略

# 语义化版本 (Semantic Versioning)
# MAJOR.MINOR.PATCH

# 1.0.0 -> 1.0.1 (patch: 修复)
# 1.0.0 -> 1.1.0 (minor: 新功能)  
# 1.0.0 -> 2.0.0 (major: 破坏性更改)

3. 分支策略

# 推荐的分支模型
main/master    # 生产分支，自动发布
develop        # 开发分支，CI 检查
feature/*      # 功能分支
hotfix/*       # 热修复分支

4. 发布前检查清单

  • 所有测试通过
  • 代码覆盖率达标
  • 文档已更新
  • CHANGELOG.md 已更新
  • 版本号符合语义化规范
  • 构建产物正常

5. 安全考虑

# 定期更新依赖
npm audit
npm update

# 使用 .npmignore 排除敏感文件
echo "*.log" >> .npmignore
echo ".env*" >> .npmignore
echo "test/" >> .npmignore

📚 相关资源

🎉 完成

现在你的项目已经配置了完整的 CI/CD 流程！

每次提交代码时：

  1. 🔄 自动运行质量检查
  2. 🏷️ 自动管理版本号
  3. 📦 自动发布到 NPM
  4. 📝 自动创建 Release

享受自动化带来的便利吧！ 🚀