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-tw/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 位置。如果仍然存在相同的錯誤，請在尋求幫助時包含該命令並清理第一個錯誤行；切勿停用訪問檢查或將機密列印到日誌中。
不要靠停用授權、記錄金鑰或把跳過的基礎設施檢查當作通過來解決失敗檢查。捕獲一個小的復現與相關的非敏感配置。修復後重跑失敗檢查，再跑受影響的迴歸測試。