Skip to content

Commit 614911b

Browse files
sansi-lcjsansi-lcj
committed
feat: 添加 GitHub Actions CI/CD 自动化配置
- 添加 CI 工作流，支持 Node.js 18/20 多版本测试 - 添加自动发布工作流，支持语义化版本和预发布版本 - 添加文档自动部署工作流 - 更新 README 添加徽章和发布流程说明 - 添加配置指南和 PR 模板
1 parent 505db74 commit 614911b

File tree

6 files changed

+511
-1
lines changed

6 files changed

+511
-1
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
## 变更说明
2+
3+
<!-- 请简要描述此 PR 的目的和变更内容 -->
4+
5+
## 变更类型
6+
7+
<!-- 请勾选适用的选项 -->
8+
9+
- [ ] 🐛 Bug 修复
10+
- [ ] ✨ 新功能
11+
- [ ] 📝 文档更新
12+
- [ ] 🎨 样式改进
13+
- [ ] ♻️ 代码重构
14+
- [ ] ⚡️ 性能优化
15+
- [ ] ✅ 测试相关
16+
- [ ] 🔧 配置/构建工具
17+
- [ ] 🔥 移除代码或文件
18+
19+
## 相关 Issue
20+
21+
<!-- 如果有相关的 issue，请在此处引用 -->
22+
23+
Closes #
24+
25+
## 测试情况
26+
27+
<!-- 描述你如何测试了这些变更 -->
28+
29+
- [ ] 本地开发环境测试通过
30+
- [ ] 测试应用构建成功
31+
- [ ] CI 检查通过
32+
33+
## 截图（如适用）
34+
35+
<!-- 如果是 UI 相关的变更，请添加截图 -->
36+
37+
## 检查清单
38+
39+
<!-- 在提交 PR 前，请确认以下事项 -->
40+
41+
- [ ] 代码遵循项目的编码规范
42+
- [ ] 已添加/更新相关文档
43+
- [ ] 变更不会破坏现有功能
44+
- [ ] 已更新 CHANGELOG（如果是重要变更）
45+
- [ ] 提交信息清晰明了
46+
47+
## 额外说明
48+
49+
<!-- 任何需要特别说明的内容 -->

‎.github/SETUP.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# GitHub Actions 配置指南
2+
3+
本指南将帮助你配置 GitHub 仓库以使用自动化 CI/CD 工作流。
4+
5+
## 1. 配置 NPM Token
6+
7+
为了能够自动发布包到 npm，你需要配置 NPM 访问令牌：
8+
9+
### 获取 NPM Token
10+
11+
1. 登录 [npmjs.com](https://www.npmjs.com/)
12+
2. 点击头像 → **Access Tokens**
13+
3. 点击 **Generate New Token** → 选择 **Automation**
14+
4. 复制生成的 token（格式：`npm_xxxxxxxxxxxx`）
15+
16+
### 在 GitHub 中配置
17+
18+
1. 打开仓库页面：https://github.com/realsee-developer/vreo
19+
2. 进入 **Settings** → **Secrets and variables** → **Actions**
20+
3. 点击 **New repository secret**
21+
4. 配置如下：
22+
- Name: `NPM_TOKEN`
23+
- Secret: 粘贴你的 npm token
24+
5. 点击 **Add secret**
25+
26+
## 2. 启用 GitHub Pages
27+
28+
为了自动部署文档到 GitHub Pages：
29+
30+
1. 打开仓库页面：https://github.com/realsee-developer/vreo
31+
2. 进入 **Settings** → **Pages**
32+
3. 在 **Source** 下拉菜单中选择 **GitHub Actions**
33+
4. 保存设置
34+
35+
首次推送到 main 分支后，文档将自动构建并部署到：
36+
- https://realsee-developer.github.io/vreo/
37+
38+
## 3. 分支保护规则（可选但推荐）
39+
40+
为了确保代码质量，建议配置分支保护：
41+
42+
1. 进入 **Settings** → **Branches**
43+
2. 点击 **Add rule**
44+
3. 配置如下：
45+
- **Branch name pattern**: `main` 或 `master`
46+
- ✅ **Require a pull request before merging**
47+
- ✅ **Require status checks to pass before merging**
48+
- 搜索并选择 `build` (来自 CI workflow)
49+
- ✅ **Require branches to be up to date before merging**
50+
4. 保存规则
51+
52+
这样可以确保：
53+
- 所有代码都必须通过 Pull Request 合并
54+
- 合并前必须通过 CI 检查
55+
- 防止直接推送到 main 分支
56+
57+
## 4. 工作流说明
58+
59+
### CI Workflow (ci.yml)
60+
61+
**触发时机**:
62+
- 创建或更新 Pull Request
63+
- 推送到 main/master 分支
64+
65+
**执行内容**:
66+
- Node.js 18 和 20 版本矩阵测试
67+
- 安装依赖
68+
- 构建主包和测试应用
69+
70+
**查看结果**: PR 页面会显示检查状态
71+
72+
### Publish Workflow (publish.yml)
73+
74+
**触发时机**:
75+
- 推送版本标签（如 `v2.6.4`）
76+
77+
**执行内容**:
78+
- 构建生产包
79+
- 发布到 npm
80+
- 创建 GitHub Release
81+
- 同步到 cnpm（如果配置）
82+
83+
**版本规则**:
84+
- `v2.6.4` → npm `latest` tag（正式版本）
85+
- `v2.7.0-alpha.1` → npm `alpha` tag（Alpha 测试版）
86+
- `v2.7.0-beta.1` → npm `beta` tag（Beta 测试版）
87+
- `v2.7.0-rc.1` → npm `rc` tag（Release Candidate）
88+
89+
### Docs Workflow (docs.yml)
90+
91+
**触发时机**:
92+
- 推送到 main/master 分支
93+
- 推送版本标签
94+
- 手动触发（Actions 页面）
95+
96+
**执行内容**:
97+
- 使用 TypeDoc 生成 API 文档
98+
- 部署到 GitHub Pages
99+
100+
## 5. 发布新版本
101+
102+
完整的发布流程：
103+
104+
```bash
105+
# 1. 确保在最新的 main 分支
106+
git checkout main
107+
git pull origin main
108+
109+
# 2. 更新版本号
110+
cd packages/vreo
111+
npm version patch # 或 minor/major/prerelease
112+
113+
# 3. 推送代码和标签
114+
git push origin main
115+
git push origin --tags
116+
117+
# 4. 等待 GitHub Actions 自动发布
118+
# 访问 https://github.com/realsee-developer/vreo/actions 查看进度
119+
```
120+
121+
## 6. 查看工作流状态
122+
123+
所有工作流的执行状态可以在这里查看：
124+
- https://github.com/realsee-developer/vreo/actions
125+
126+
每个工作流都有详细的日志，可以帮助你诊断问题。
127+
128+
## 7. 徽章（Badges）
129+
130+
README 中已经添加了以下徽章：
131+
132+
- **CI Status**: 显示 CI 构建状态
133+
- **NPM Version**: 显示最新发布的版本
134+
- **NPM Downloads**: 显示下载量统计
135+
- **License**: 显示开源许可证
136+
137+
这些徽章会自动更新，无需手动维护。
138+
139+
## 常见问题
140+
141+
### Q: 发布失败，显示 "Invalid authentication token"
142+
143+
A: 检查 NPM_TOKEN 是否正确配置，token 是否过期。
144+
145+
### Q: GitHub Pages 部署失败
146+
147+
A: 确认已在 Settings → Pages 中选择了 "GitHub Actions" 作为源。
148+
149+
### Q: CI 检查一直在运行
150+
151+
A: 检查 Actions 页面的日志，可能是构建过程中出现了错误。
152+
153+
### Q: 如何跳过 CI 检查？
154+
155+
A: 在 commit 消息中添加 `[skip ci]` 或 `[ci skip]`（不推荐）。
156+
157+
## 更多帮助
158+
159+
- [GitHub Actions 文档](https://docs.github.com/en/actions)
160+
- [npm 发布文档](https://docs.npmjs.com/cli/v9/commands/npm-publish)
161+
- [GitHub Pages 文档](https://docs.github.com/en/pages)

‎.github/workflows/ci.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
pull_request:
9+
branches:
10+
- main
11+
- master
12+
13+
jobs:
14+
build:
15+
name: Build and Test
16+
runs-on: ubuntu-latest
17+
18+
strategy:
19+
matrix:
20+
node-version: [18.x, 20.x]
21+
22+
steps:
23+
- name: Checkout code
24+
uses: actions/checkout@v4
25+
26+
- name: Setup pnpm
27+
uses: pnpm/action-setup@v2
28+
with:
29+
version: 8.15.0
30+
31+
- name: Setup Node.js ${{ matrix.node-version }}
32+
uses: actions/setup-node@v4
33+
with:
34+
node-version: ${{ matrix.node-version }}
35+
cache: 'pnpm'
36+
37+
- name: Install dependencies
38+
run: pnpm install --frozen-lockfile
39+
40+
- name: Build main package
41+
run: pnpm build
42+
43+
- name: Build test app
44+
run: pnpm test:build
45+
46+
- name: Check package contents
47+
run: |
48+
cd packages/vreo
49+
ls -la lib/
50+
echo "✓ Build artifacts verified"

‎.github/workflows/docs.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- master
8+
tags:
9+
- 'v*.*.*'
10+
workflow_dispatch:
11+
12+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
# Allow only one concurrent deployment
19+
concurrency:
20+
group: "pages"
21+
cancel-in-progress: false
22+
23+
jobs:
24+
build:
25+
name: Build Documentation
26+
runs-on: ubuntu-latest
27+
28+
steps:
29+
- name: Checkout code
30+
uses: actions/checkout@v4
31+
32+
- name: Setup pnpm
33+
uses: pnpm/action-setup@v2
34+
with:
35+
version: 8.15.0
36+
37+
- name: Setup Node.js
38+
uses: actions/setup-node@v4
39+
with:
40+
node-version: '20.x'
41+
cache: 'pnpm'
42+
43+
- name: Install dependencies
44+
run: pnpm install --frozen-lockfile
45+
46+
- name: Build documentation
47+
run: pnpm docs
48+
49+
- name: Setup Pages
50+
uses: actions/configure-pages@v4
51+
52+
- name: Upload artifact
53+
uses: actions/upload-pages-artifact@v3
54+
with:
55+
path: './packages/vreo/docs'
56+
57+
deploy:
58+
name: Deploy to GitHub Pages
59+
environment:
60+
name: github-pages
61+
url: ${{ steps.deployment.outputs.page_url }}
62+
runs-on: ubuntu-latest
63+
needs: build
64+
65+
steps:
66+
- name: Deploy to GitHub Pages
67+
id: deployment
68+
uses: actions/deploy-pages@v4

0 commit comments

Comments
 (0)