Files
perler-lab/docs/CI-NEWPAGES.md
T

8.0 KiB
Raw Blame History

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 配置。

建议(保持现状的三条纪律)

  1. 不要把新页面做成 public/ 下的物理 HTML 文件。Vite 会将 public/ 原样拷入 dist,若未来出现同名静态目录(如 dist/showcase/),nginx 的 try_files $uri $uri/ 会优先命中该目录而非 SPA 回退,导致路由与静态资源语义冲突。
  2. 保持 location / 的 try_files 兜底不被覆盖。新增 location 时避免写死 try_files $uri =404 之类的规则覆盖根 location。
  3. 若未来迁移到 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 → test job 失败 → 阻塞 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。