# 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 回退: ```nginx # ── 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) ```yaml - 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 → 200` 全部通过后进入 `build` job。