命令、檔案和配置

命令進入終端

終端是您為計算機輸入指令的視窗。在 Visual Studio Code 中，首先使用檔案 → 開啟資料夾開啟您的 supastack 資料夾，然後選擇終端 → 新終端。新終端在該資料夾中啟動。在 Windows 上，使用終端 + 按鈕旁邊的選單選擇 PowerShell。在 macOS 或 Linux 終端中使用 macOS/Linux 塊。

僅貼上命令塊的內容，一次一個命令，然後按 Enter。請勿貼上週圍的 Markdown 反引號、PS C:\... 等提示或示例輸出。以#開頭的行是解釋；他們不管理任何東西。等待每個安裝命令完成，然後再輸入下一個命令。伺服器命令持續執行，並且在您停止它之前不會返回新的提示。

檢查終端正在使用哪個資料夾

儲存庫根是指包含 package.json、pnpm-workspace.yaml、apps 和 packages 的頂級 supastack 資料夾。除非步驟另有說明，否則請在此處執行命令。下面的命令列印當前資料夾；檔案列表應顯示 package.json。在 Windows PowerShell pwd 和 ls 中也可以使用。

如果列表僅顯示 apps/web 或 apps/mobile 的內容，請鍵入 cd ../.. 並按 Enter 鍵返回到根目錄。如果它顯示您的主資料夾，請鍵入 cd，後跟一個空格和克隆的完整路徑，當包含空格時用引號引起來。在編輯器中開啟專案資料夾並建立新終端通常更容易。

pwd
ls

配置位於檔案中，而不是終端中

像 AI_PROVIDER=fake 這樣的塊是配置文本。在編輯器中開啟命名的 .env 檔案，找到以 AI_PROVIDER= 開頭的行，替換其值並使用 Ctrl + S（macOS 上的 Command + S）儲存。 KEY=value 形式中，每個設定佔一行。不要新增 Markdown 反引號。避免在一個檔案中重複複製同一金鑰。

使用 root .env 執行資料庫遷移命令，使用 apps/web/.env.local 執行 Next.js Web 伺服器，使用 apps/mobile/.env.local 執行 Expo。 Next 和 Expo 在它們自己的應用程式資料夾中執行，並且不會自動載入 root .env。如果資料庫連線發生更改，請更新 root .env 和 apps/web/.env.local 中的 DATABASE_URL，以便遷移和伺服器使用相同的資料庫。保持示例檔案不變以供將來參考。

名稱以點開頭的檔案可能隱藏在您的檔案管理器中；編輯器的資源管理器顯示了它們。確保檔名完全是 .env.local，而不是 .env.local.txt。這些本地檔案可以包含密碼，並且被排除在 Git 之外；不要上傳它們或將其內容貼上到支援訊息中。

• 查詢各個設定的含義

保持伺服器執行；使用另一個終端來執行命令

開發伺服器在您工作時為您的應用程式提供服務。當教程說開啟 localhost:3000 時，將其終端保持開啟狀態。 localhost 表示這臺計算機； :3000 是埠，就像應用程式使用的編號門。將 URL 放入瀏覽器的位址列，而不是終端。

要在伺服器處於活動狀態時執行另一個命令，請在編輯器中選擇 Terminal → New Terminal。新終端是同一專案的一個單獨視窗。要停止伺服器，請選擇其終端並按 Ctrl + C 一次。在 Windows 上，如果詢問終止批處理作業，請鍵入 Y 並按 Enter。等待正常提示後再重新啟動。

編輯 Web 環境設定後，使用以下命令停止並重新啟動 Web 伺服器。儲存原始檔通常會自動重新整理頁面，但環境更改需要重新啟動。編輯 Expo 設定後，停止 Expo，然後執行 ​​corepack pnpm --filter @supastack/mobile start --clear 重新啟動並清除其快取的包。

corepack pnpm --filter @supastack/web dev

閱讀失敗並尋求有用的幫助

如果安裝返回紅色錯誤文本，請停止該步驟。閱讀第一個錯誤，而不是繼續啟動應用程式。找不到命令通常意味著缺少工具；沒有package.json通常意味著錯誤的資料夾； ECONNREFUSED通常表示所需的伺服器或資料庫未執行； EADDRINUSE 表示另一個程式已使用該埠。

尋求幫助時，請提供您的作業系統、指南 URL 和步驟號、您輸入的確切命令以及第一條錯誤訊息。刪除任何資料庫 URL 的密碼、API 金鑰、令牌和密碼部分。不要傳送您的 .env 檔案。錯誤的螢幕截圖可能會有所幫助，但可複製的文本更容易診斷。

• 解決特定設定失敗