当前部署方式

• 主分支：master
• 部署平台：GitHub Pages
• 发布来源：GitHub Actions
• 自定义域名：run.aiyuanzi.cn
• 前端构建输出目录：dist

仓库里有两条关键工作流：

• .github/workflows/run_data_sync.yml 负责同步运动数据、生成静态资源
• .github/workflows/gh-pages.yml 负责构建前端并发布 GitHub Pages

Run Data Sync 成功后，会继续触发 Publish GitHub Pages。

GitHub Pages 必须怎么配

进入 GitHub 仓库后台：

1. 打开 Settings -> Pages
2. 找到 Build and deployment
3. 将 Source 设为 GitHub Actions

不要选择 Deploy from a branch。

原因很简单：
如果直接从分支发布，GitHub Pages 会把仓库源码根目录直接当网站目录使用，而不是发布 vite build 之后的 dist。

自动同步频率

当前定时任务配置是：

含义：

• 每天执行一次
• 按 UTC 时间是 00:00
• 按北京时间是每天 08:00

除了定时执行，还会在下面情况触发：

• 你手动运行工作流
• 你 push 了工作流监听的相关文件

怎么手动同步一次

如果不想等自动任务：

1. 打开 GitHub 仓库
2. 进入 Actions
3. 选择 Run Data Sync
4. 点击 Run workflow

这一步会做三件事：

• 同步数据
• 生成静态资源
• 自动触发 GitHub Pages 发布

如果只想重新发布页面

如果数据没问题，只想重新部署前端：

1. 打开 GitHub 仓库
2. 进入 Actions
3. 选择 Publish GitHub Pages
4. 点击 Run workflow

这会直接重新构建并发布 dist。

常用命令和作用

下面这些命令适合在仓库根目录执行。

前端开发相关

作用：

• 安装 Node 依赖
• 第一次拉代码后通常先执行这个

作用：

• 启动本地开发服务器
• 用来本地查看页面效果和调试
• 一般访问终端输出里的本地地址

数据相关

作用：

• 手动执行 Garmin 数据同步脚本
• 实际使用时通常还要带认证参数或 secret
• GitHub Actions 里也是基于这些脚本在跑

作用：

• 基于数据库重新生成统计图资源
• 常用于检查资源是否能正常产出

作用：

• 调用上面的 gen_svg.py 命令
• 快速重新生成 assets/github.svg

作用：

• 清空本地数据库和中间产物
• 会删除 run_page/data.db、活动数据和导出文件
• 这是破坏性命令，只有明确要重置本地数据时再执行

这次遇到的两个典型报错

报错 1

报错 2

这两个报错说明什么

这两个报错通常意味着同一个问题：

• 页面发布的是源码目录
• 不是 Vite 构建后的 dist

因为源码里的 index.html 仍然保留着：

• src="/src/main.tsx"
• href="%BASE_URL%/images/favicon.png"

只有执行 vite build 后，这些路径才会被替换成真正的静态资源地址。

常用配置项

修改自动同步频率

修改 cron 表达式，例如：

• 每 6 小时一次：0 */6 * * *
• 每天北京时间凌晨 1 点：0 17 * * *

注意：GitHub Actions 的 cron 使用 UTC 时间。

是否同步后自动发布 GitHub Pages

工作流中有这个变量：

含义：

• true：同步完成后自动发布页面
• false：只同步数据，不发布页面

是否把中间数据放进 GitHub Actions Cache

工作流中还有这个变量：

如果主要使用 GitHub Pages，通常建议设成 true，这样可以减少仓库里频繁提交大量中间文件。

一句话结论

GitHub Pages 必须通过 GitHub Actions 发布 dist，不能直接发布源码分支。