8.0 KiB
CI 门禁:色号表与 Showcase 等新页面构建检查(T-109)
维护者:GitOps-Engineer(T-109) 关联文件:
.github/workflows/deploy.yml、perler-lab/nginx.conf、perler-lab/src/App.tsx更新日期:2026-08-14
检查结论(TL;DR)
| 检查项 | 结论 |
|---|---|
| 新页面是否影响现有构建? | 不破坏。新页面均通过 App.tsx 顶层静态 import 打包进同一 Vite bundle,typecheck + vite build 天然覆盖 |
| Vite build 是否自动打包新路由页面? | 是。路由为 App.tsx 内基于 window.location.pathname 的客户端分支(非 react-router 动态加载),无按路由分包,全部页面一次性打进 assets/index-*.js |
| SPA 路由是否需要 Nginx / fallback 配置? | 已具备,无需新增。perler-lab/nginx.conf 已配置 try_files $uri $uri/ /index.html;,新路由直访由 nginx 回退到 index.html 后由前端渲染 |
| 是否需要新增 CI 门禁? | 需要小补强。已新增「Verify SPA dist & route smoke」步骤:校验 dist 产物 + 用 vite preview 对每个新路由做直访冒烟,防「路由直访 404」回归 |
| 是否改动 deploy.yml? | 是。test job 的 Frontend production build 步骤之后新增一个产物校验 + 路由冒烟步骤(见下文) |
① 新页面构建验证清单(typecheck / build 覆盖确认)
新页面与路由清单
| 路由 | 页面组件 | 源码位置 |
|---|---|---|
/chibi、/chibi/* |
ChibiPage |
perler-lab/src/ChibiPage.tsx |
/color-chart、/color-chart/:brand |
ColorChartPage |
perler-lab/src/ColorChartPage.tsx(数据 src/lib/color-chart-data.ts + src/lib/palette-data/*.json) |
/showcase、/showcase/* |
ShowcasePage |
perler-lab/src/pages/ShowcasePage.tsx |
/library、/library/* |
LibraryPage |
perler-lab/src/pages/LibraryPage.tsx |
| 其他任意路径 | HomePage(兜底) |
perler-lab/src/App.tsx |
覆盖确认
- 路由实现方式:
App.tsx(src/App.tsx第 335–348 行)在顶层静态 import 全部页面组件(import ColorChartPage from './ColorChartPage'等),再按window.location.pathname分支渲染。无 react-router、无React.lazy动态加载。 - typecheck 覆盖(G3):
npm run typecheck=tsc --noEmit(tsconfig.json开启strict)。新增页面的.tsx/.ts源码全部参与编译,类型错误会直接拦截。CI 矩阵中perler-lab与perler-lab-server均执行。 - build 覆盖(G4):
npm run build=vite build。由于所有页面为静态 import,新页面组件 + 色号 JSON 数据 + CSS 必然被 Rollup 打包进dist/assets/index-*.js。构建产物中不存在“漏掉某个路由页面”的空间——只要 App.tsx 引用了它,就会进 bundle;引用缺失则 tsc 直接报错(Cannot find module)。 - 产物校验:CI 新增步骤显式断言
dist/index.html与dist/assets/*.js存在,确认产物完整性。
结论:无需为新页面单独新增 build 命令。现有 G3(typecheck)+ G4(vite build)已完整覆盖;T-109 仅在其后增加产物校验与路由冒烟,作为“构建成功”之外的“构建产物可直访”门禁。
发现的问题(非阻塞)
/help路由在App.tsx中不存在(src/App.tsx无/help分支),且全局无HelpPage组件。直访/help会落到HomePage兜底,不会 404,但展示内容与预期不符。若help属于已规划页面(如 T-109 上下文提到的 4 个新页面之一),需在后续任务中补充路由与组件;若为误报,可忽略。
② SPA fallback 部署配置建议
现状:已配置,无需改动
perler-lab/nginx.conf 已包含 SPA 回退:
# ── SPA 路由回退 ──
location / {
try_files $uri $uri/ /index.html;
}
行为:直访 /color-chart/mard → nginx 找不到对应文件 → 回退 index.html → 前端 App.tsx 读 location.pathname → 渲染 ColorChartPage。新路由无需任何额外 Nginx 配置。
建议(保持现状的三条纪律)
- 不要把新页面做成
public/下的物理 HTML 文件。Vite 会将public/原样拷入 dist,若未来出现同名静态目录(如dist/showcase/),nginx 的try_files $uri $uri/会优先命中该目录而非 SPA 回退,导致路由与静态资源语义冲突。 - 保持
location /的 try_files 兜底不被覆盖。新增 location 时避免写死try_files $uri =404之类的规则覆盖根 location。 - 若未来迁移到 Next.js / SSR,此配置需改为上层反代(
nginx.conf顶部注释已说明,参考docs/DEPLOY.md),届时 SPA fallback 职责转移,与本门禁解耦。
测试环境等价验证
CI 路由冒烟使用 vite preview(自带 history fallback),其行为与生产 nginx 的 try_files $uri $uri/ /index.html 等价:直访任意路由返回 index.html(HTTP 200)。注意 vite preview 只验证“fallback 语义正确”,无法覆盖 nginx 语法/配置错误——nginx 配置有效性仍需在 build job 的 docker 镜像构建阶段(COPY nginx.conf + nginx:alpine 启动)保证,或本地 docker run 验证。
③ CI 门禁建议(已落地到 deploy.yml)
建议结论
需要在 test job 增加路由冒烟检查。理由:
- typecheck/build 只能证明“代码可编译、页面已打包”,不能证明“直访新路由返回 200”;
- 若未来有人误删
try_files或把路由改坏,冒烟检查会在 CI 期拦截,避免部署后用户直访 404; - 成本极低(一次
vite preview+ 7 个 curl),并入现有 test job 矩阵的 perler-lab 分支即可。
已新增步骤(deploy.yml → test job)
- name: Verify SPA dist & route smoke
if: matrix.project.name == 'perler-lab'
working-directory: perler-lab
run: |
set -e
[ -f dist/index.html ] || { echo "❌ dist/index.html 缺失"; exit 1; }
ls dist/assets/*.js > /dev/null 2>&1 || { echo "❌ dist/assets 无 JS bundle"; exit 1; }
npx vite preview --port 4173 --strictPort > /tmp/vite-preview.log 2>&1 &
PID=$!
trap "kill $PID 2>/dev/null || true" EXIT
for i in $(seq 1 30); do
curl -sf http://localhost:4173/ > /dev/null 2>&1 && break
sleep 0.5
done
curl -sf http://localhost:4173/ > /dev/null 2>&1 || {
echo "❌ vite preview 未能启动"; cat /tmp/vite-preview.log; exit 1; }
for route in / /chibi /color-chart /color-chart/mard /color-chart/artkal-c /showcase /library; do
code=$(curl -s -o /dev/null -w '%{http_code}' "http://localhost:4173$route")
echo "GET $route → $code"
[ "$code" = "200" ] || { echo "❌ 路由 $route 返回 $code(预期 200)"; exit 1; }
done
要点说明:
- 冒烟路由集:
/(首页)、/chibi、/color-chart(列表)、/color-chart/mard与/color-chart/artkal-c(品牌子路由,覆盖“带段路由直访”)、/showcase、/library。未加/help(见①,该路由当前不存在)。 - 若未来新增品牌(如
/color-chart/perler),建议同步追加到路由集;也可改为读取COLOR_CHART_BRANDS动态断言,但会增加 CI 脚本复杂度,暂不引入。 - 冒烟失败(任一路由非 200 或产物缺失)→ 步骤退出码非 0 →
testjob 失败 → 阻塞build/deploy,符合门禁语义。
变更记录(T-109)
| 变更 | 文件 |
|---|---|
| 新增「Verify SPA dist & route smoke」步骤:dist 产物校验 + vite preview 对新路由直访冒烟 | .github/workflows/deploy.yml |
| 新增本文档(构建验证清单 / SPA fallback 说明 / CI 门禁建议) | docs/CI-NEWPAGES.md |
验证方式(CI 执行)
推送 master 后观察 Actions 流水线:test job(perler-lab 分支)应依次出现 Frontend production build → Verify SPA dist & route smoke,日志中 7 个 GET <route> → 200 全部通过后进入 build job。