修复记录

附件：E:\js_web\js_spa_router_blog\issues\生产构建问题汇总.md
生产构建问题汇总.md文件通过kimi聊天窗口中的分享按钮中的复制而得到。

需求： 请你从附件《生产构建问题汇总.md》的第一个问题：
“根据《操作说明文档》，当前我进行到了（8.3）预览生产构建这一步。
你提到了验证要点：
1.查看页面源代码（Ctrl+U），确认包含完整 HTML 内容
...
暂时不要输出任何代码，仅作文字交流。”
开始到最后一个问题。
请将所有关于生产构建遇到的问题和对应的成功解决方案（包括正确分析），形成一份具有先后顺序的简要的修复记录（包括问题概括，问题类别，问题原因，分析方法，最佳解决方法）
注意：只提取得到用户成功反馈和LLM分析绝对正确的问题，否则不提取，代码部分可以忽略。

请先基于我的需求，使用COT方式帮我分析我的它是否合理以及需要优化？如果需要优化，请帮我先优化它，然后输出给我

  • kimi回复得到以下优化后的需求：

优化后的需求
请从附件《生产构建问题汇总.md》的第一个问题开始到最后一个问题，将所有用户明确确认已解决且具备分析逻辑闭环的问题，按时间先后顺序整理为一份修复记录。 每条记录包含：

  • 序号：修复顺序
  • 问题概括：一句话描述
  • 问题类别：环境配置 / API与权限 / 路径引用 / 构建流程等（其他的可以通过问题描述进行提炼）
  • 影响范围：影响的功能或页面
  • 问题原因：根因分析
  • 排查思路：从现象到根因的推理过程
  • 最佳解决方法：最终验证成功的方案
  • 验证状态：用户已确认 / 逻辑推断（仅用户明确确认的问题收录）
  • 输出格式：采用markdown纵向罗列，不要使用markdown表格。
  • kimi
  • 20260724 06:19

我来重新整理修复记录，采用纵向 Markdown 格式输出。

生产构建问题修复记录

问题 1：SSG 未执行，dist 目录无静态页面

问题类别：构建流程

影响范围：所有 SSG 页面（posts、categories、tags、about、sitemap 等）

问题原因：package.json 的 build 脚本仅执行 vite build，缺少 node build-ssg.js 步骤；同时 vite.config.js 的 writeBundle 钩子缺失，导致 SSG 脚本完全未被调用。

排查思路：

  1. 观察到 npm run build 后 dist 目录只有 Vite 默认输出（index.html、assets/、robots.txt），无 posts/、categories/、tags/ 等子目录
  2. 检查 package.json 发现 build 脚本仅执行 vite build，无 SSG 步骤
  3. 检查 vite.config.js 确认无 writeBundle 钩子
  4. 推断 SSG 脚本从未被调用，构建流程不完整

最佳解决方法：修改 package.json 的 build 脚本为 "vite build && node --env-file=.env build-ssg.js"，通过 && 串联 Vite 构建和 SSG 脚本执行。

验证状态：✅ 用户已确认

问题 2：node build-ssg.js 执行后无输出

问题类别：构建流程

影响范围：同上，阻断所有 SSG 页面生成

问题原因：build-ssg.js 仅导出了 generateSSG 函数，未在模块顶层自动调用该函数。作为 ESM 模块，加载后函数定义完成即结束，不会自动执行。

排查思路：

  1. 执行 node --env-file=.env build-ssg.js 后终端无任何输出
  2. 检查 build-ssg.js 发现只有 export async function generateSSG()，无调用语句
  3. 理解 ESM 模块加载机制：导入模块只执行顶层代码，导出函数不会自动调用
  4. 推断需要在文件末尾添加自动执行逻辑

最佳解决方法：在 build-ssg.js 文件末尾添加 generateSSG().catch(err => { console.error('❌ SSG failed:', err); process.exit(1); }); 实现模块自执行。

验证状态：✅ 用户已确认

问题 3：SSG 执行时 TLS 证书验证失败

问题类别：环境配置

影响范围：阻断所有 GitHub API 请求，SSG 完全无法执行

问题原因：本地网络环境存在代理工具（WattToolkit / Steam++）拦截 HTTPS 连接，替换了 GitHub API 的 SSL 证书，导致 Node.js 的 TLS 证书链验证失败。

排查思路：

  1. 报错信息为 unable to verify the first certificate，错误码 UNABLE_TO_VERIFY_LEAF_SIGNATURE
  2. 检查 HTTP 响应头发现 server: 'github.com, WattToolkit'，确认代理工具介入
  3. 确认 GitHub API 服务端本身无证书问题，问题出在本地网络层
  4. 推断需要临时禁用 Node.js 的 TLS 验证以绕过本地代理的证书替换

最佳解决方法：在 PowerShell 中执行 $env:NODE_TLS_REJECT_UNAUTHORIZED="0" 临时禁用 TLS 证书验证，然后执行 npm run build。

验证状态：✅ 用户已确认

问题 4：GitHub API 返回 404，discussions/categories 端点不存在

问题类别：API 与权限

影响范围：分类列表页、分类详情页生成失败

问题原因：discussions/categories 不是 GitHub REST API v3 的有效端点，该端点仅存在于 GraphQL API 中。build-ssg.js 中使用了错误的 API 路径。

排查思路：

  1. 报错 404，请求 URL 为 https://api.github.com/repos/stuffren/chunking-blog/discussions/categories
  2. 检查 x-oauth-scopes 确认 Token 已包含 read:discussion 和 repo 权限，排除权限问题
  3. 查阅 GitHub REST API 文档，确认 discussions/categories 端点不存在于 v3
  4. 推断应从 discussions 响应数据中提取 category 字段来构建分类信息

最佳解决方法：移除对 discussions/categories 的 API 调用，改为从 discussions 响应数据中遍历提取 category 字段，使用 Map 去重后构建分类列表。

验证状态：✅ 用户已确认

问题 5：build-ssg.js 的 rm(DIST_DIR) 删除 Vite 构建产物

问题类别：构建流程

影响范围：assets/ 目录、robots.txt 等 Vite 构建输出文件被删除，导致生产环境缺少 JS/CSS 和 SEO 文件

问题原因：generateSSG 函数开头执行 rm(DIST_DIR, { recursive: true })，清空了 Vite 已生成的 assets/ 目录和 robots.txt，随后 SSG 只重新生成了 HTML 文件。

排查思路：

  1. 发现 SSG 页面（posts/1.html 等）生成成功，但 assets/ 目录和 robots.txt 消失
  2. 检查 build-ssg.js 发现 rm(DIST_DIR) 在 generateSSG 开头执行
  3. 梳理执行顺序：Vite 构建 → 生成 dist/assets/ 和 robots.txt → SSG 执行 → rm 删除整个 dist/ → 重新创建空目录 → 只写入 SSG HTML 文件 → Vite 产物丢失
  4. 推断应移除 rm 操作，改为仅确保目录存在

最佳解决方法：删除 rm(DIST_DIR, { recursive: true }) 语句，仅保留 mkdir(DIST_DIR, { recursive: true }) 确保目录存在即可。

验证状态：✅ 用户已确认

问题 6：SSG 生成的 HTML 引用开发环境路径，生产环境样式/脚本 404

问题类别：路径引用

影响范围：所有 SSG 生成的静态页面（posts/1.html、categories.html、tags.html 等）

问题原因：pageTemplate 函数硬编码了开发环境路径（/src/styles/*.css、/src/main.js），而生产构建后文件已被 Vite 打包到 assets/ 目录且文件名包含内容哈希（如 main-B33Ixunb.js）。

排查思路：

  1. 预览生产构建时打开 http://localhost:4173/posts/1，发现页面无样式、无交互
  2. 查看页面源代码，发现引用 /src/styles/variables.css、/src/styles/base.css 等开发路径
  3. 对比 Vite 构建输出，确认实际路径为 assets/main-B33Ixunb.js 和 assets/main-Dix6Oozi.css
  4. 推断 pageTemplate 模板未适配生产环境，需要动态读取 Vite 构建后的 assets 路径

最佳解决方法：

  1. 在 generateSSG 开头读取 Vite 构建后的 dist/index.html
  2. 使用正则提取 assets/main-*.js 和 assets/main-*.css 的实际路径
  3. 修改 pageTemplate 函数：移除所有 /src/styles/*.css 引用，改为注入动态提取的 assets.css 和 assets.js 路径

验证状态：✅ 用户已确认

修复记录总结

问题类别 涉及问题
构建流程 问题 1、问题 2、问题 5
环境配置 问题 3
API 与权限 问题 4
路径引用 问题 6

核心依赖链：问题 1 → 问题 2 → 问题 3 → 问题 4 → 问题 5 → 问题 6，后一个问题的修复依赖于前一个问题的成功解决。