For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/web/troubleshooting.md (or send Accept: text/markdown).
故障排查
在实际失败的边界处诊断安装问题。
安装与配置
在执行任何步骤之前，请阅读开始之前 和终端基础知识。这些说明假设您在 VS Code 中打开了完整的 supastack monorepo；它的根 package.json 标记存储库根。在 pnpm 命令中，工作区包是应用程序或共享代码文件夹；在产品中，工作空间是团队的数据容器和安全边界。 corepack pnpm --filter ... 从 monorepo 选择一个包，同时从其根运行命令。如果您仅打开同步的移动或桌面文件夹，则它不包含 Web 后端、Docker 设置或根脚本：从此 monorepo 或可访问的托管服务器运行后端，并使用平台文件夹自己的脚本。环境变量是存储在本地 .env 文件或托管仪表板中的命名设置；更改后重新启动相关应用程序，并将服务器机密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。
1. 复制第一个有用的错误行和产生它的命令；不要粘贴秘密值。
2. 从存储库根目录运行 corepack pnpm --filter @supastack/web typecheck（针对 Web 类型错误）或 corepack pnpm test（针对自动化套件）。
3. 对于浏览器问题，使用 corepack pnpm --filter @supastack/web dev 启动 Web 并在 http://localhost:3000. 重现它 预期：在更改设置之前，您可以判断故障是否出在设置、代码、数据库、提供程序或浏览器中。
改配置之前，先读失败的命令与第一个相关错误。判断失败发生在依赖安装、编译、环境校验、数据库访问、供应商派发还是浏览器行为。
corepack pnpm --filter @supastack/web typecheck
corepack pnpm --filter @supastack/web build
corepack pnpm test要复制的命令
按照注释查看命令在哪个文件夹中运行。如果标记了两个终端，请打开两个终端窗口，并在使用第二个命令时保持第一个命令运行。
corepack pnpm --filter @supastack/web typecheck
corepack pnpm test首次运行报错速查
首次运行失败的方式就那么几种。把第一行红色错误对应到表中的一行——后面的错误通常是第一个的连带后果，先修最上面的那个。
| 症状 | 可能的原因 | 首先修复 |
|---|---|---|
| node、corepack 或 pnpm 提示“不是内部或外部命令”/ command not found | 工具未安装，或终端在安装完成前就打开了 | 安装它（或重新打开终端），然后重试 node --version |
| 找不到 package.json / ENOENT package.json | 终端所在的文件夹不对 | cd 进存储库根目录——包含 package.json 的文件夹——再重试 |
| EADDRINUSE / 端口 3000 已被占用 | 另一个开发服务器仍占用该端口 | 找到那个服务器的终端并按 Ctrl + C，然后重新启动 |
| ECONNREFUSED localhost:5432 或数据库连接错误 | Postgres 没在运行 | 运行 docker compose up -d postgres，等到 healthy 再重试 |
| 环境校验报错并指出缺失的键名 | apps/web/.env.local 缺失，或某个必填值为空 | 从 .env.example 复制那个指名的键，填上值，保存并重启服务器 |
| corepack enable 之后 corepack 或 pnpm 仍找不到 | PATH 上没有 pnpm shim | 直接用 corepack pnpm ...——它从不需要 shim；Windows 上用 corepack.cmd |
| PowerShell 提示 .ps1 脚本无法运行 / 被阻止 | PowerShell 的脚本策略拦下了 shim | 改用 .cmd 形式——corepack.cmd pnpm install——无需改策略 |
实现流程
API 访问缺失时，确认服务器在运行且配置的 origin 与客户端一致。AI 选项不可用时，检查 AI_MODEL_POLICY 与已启用的目录行。排队状态不确定的任务，走已保存的恢复流程而不是再提交一次。
浏览器布局问题，检查计算样式并复现精确视口。产品界面 token 在 app-theme.css（配色包来自 catalog.ts）；营销品牌锁定在 theme.css。组件覆盖仍可能靠优先级胜出。要看渲染出来的圆角，而不只是 token 声明。
验证与排障
如果页面位于 :3001，则为 Web 应用程序打开 :3000； :3001属于单独的apps/docs服务器。如果测试要求访问数据库，请使用独立的开发数据库并检查两个 .env 位置。如果仍然存在相同的错误，请在寻求帮助时包含该命令并清理第一个错误行；切勿禁用访问检查或将机密打印到日志中。
不要靠禁用授权、记录密钥或把跳过的基础设施检查当作通过来解决失败检查。捕获一个小的复现与相关的非敏感配置。修复后重跑失败检查，再跑受影响的回归测试。