🛠️ 故障排查与调试指南

本指南涵盖了在使用 Instant Ship™ 脚手架开发时遇到的最常见的技术障碍。

0. 🚑 操作协议：利用 Bug 矩阵 (请先阅读)

目标： 在从头开始调试之前，使用我们“已捕获的幽灵”档案来定位和修复问题。

我们在 docs/instantship/bug_records.md 中维护了一个已解决技术债务的严格日志。这是你的第一道防线。

3 步解决工作流

捕捉症状
- 控制台错误：例如，Minified React error #525 或 ReferenceError: process is not defined。
- 行为：例如，“加载时白屏”或“刷新特定页面时 404”。
模式匹配
- 打开 docs/instantship/bug_records.md。
- 搜索您的特定错误代码或关键字。
- 识别唯一的 [FIX-ID]。
执行协议
- 转到该特定记录的“3. 解决方案实施”部分。
- 完全复制该代码片段。这些修复方案已经过架构验证。

常见症状图

症状	可能原因	目标记录
白屏 (无渲染)	React 版本不匹配 / Importmap 问题	`[FIX-002]`
`process is not defined`	缺少环境垫片	`[FIX-002]` (B 阶段)
刷新时 404 (Cloudflare)	缺少 `_redirects` 配置	`[FIX-001]`
路由失败 (AI Studio)	Blob URL 安全 / 源不匹配	`[FIX-001]`

1. “白屏死机” (React Error #525)

症状：控制台显示 Error #525 或提及 Suspense 不匹配。原因：这几乎总是由“多重 React 实例冲突”引起的。如果一个库（如 TanStack 或 i18next）引入了它自己的 React 版本，而不是使用宿主实例，React Dispatcher 就会崩溃。修复：

检查 index.html importmap。确保每个库都附加了 ?external=react,react-dom。
验证所有与 React 相关的导入都使用完全相同的版本 (例如, 19.2.3)。

2. "process is not defined"

症状：应用立即崩溃，并出现 ReferenceError。原因：现代库经常检查 process.env.NODE_ENV，这在浏览器中不存在。修复：确保在 index.html 的 <head> 中存在 process shim：


html
<script>window.process = { env: { NODE_ENV: 'development' } };</script>

3. 刷新页面时 404 (Cloudflare)

症状：导航工作正常，但刷新像 /blog 这样的 URL 会返回 Cloudflare 404。原因：单页应用 (SPA) 需要服务器将所有路径重定向到 index.html。修复：确保 public/_redirects 包含 /* /index.html 200。

4. 在 AI Studio / 沙箱中路由失败

症状：点击链接无反应或抛出 Origin/Security 错误。原因：blob: 或 usercontent.goog 域上的安全策略阻止了 pushState。修复：脚手架在这些环境中会自动切换到 HashHistory。如果你强制指定了历史记录类型，请检查 index.tsx 中的 isSandbox 逻辑。

5. 元数据/SEO 不更新

症状：社交分享显示旧的标题或描述。原因：Helmet 可能与静态标签冲突。修复：专门使用 <SEO /> 组件并确保 site.config.ts 已更新。运行 npm run build 以重新生成 sitemap。

故障排查指南