命令、檔案和配置

命令進入終端

終端是您為計算機輸入指令的視窗。在 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/mobile 的內容，輸入 cd ../.. 並按 Enter 返回根目錄。如果顯示的是您的主資料夾，輸入 cd 加空格再加上克隆的完整路徑（含空格時用引號括起來）。通常更簡單的做法是在編輯器中開啟專案資料夾並新建一個終端。

pwd
ls

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

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

Expo 使用 apps/mobile/.env.local，資料庫遷移命令使用根目錄的 .env。Expo 不會自動載入根目錄的 .env。Web 後端讀取它自己的 apps/web/.env.local；在僅含 Mobile 的 checkout 中，該檔案屬於單獨的後端儲存庫，而不是這一個。如果後端地址有變，請更新 apps/mobile/.env.local 中的 EXPO_PUBLIC_API_URL 並重啟 Expo。請保留示例檔案原樣以備日後參考。

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

• 查詢各個設定的含義

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

Expo 開發伺服器在您工作時把介面推送到手機或模擬器。當教程要求掃碼時，請保持它的終端處於開啟狀態。伺服器命令會持續執行，在您停止它之前不會返回新的提示符。

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

修改 Expo 設定後，用 Ctrl + C 停止 Expo，然後執行下面的命令重啟並清除快取的構建產物。儲存原始檔通常會自動重新整理預覽，但環境變數的更改需要重啟。

corepack pnpm --filter @supastack/mobile start --clear

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

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

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

• 解決特定設定失敗