卡關 FAQ

萬能救援句

懶得找、或情況不在清單上，直接用這三句，適用任何錯誤。

我在做一個專案時遇到這個錯誤，我是零基礎，請用最白話的方式告訴我：這是什麼意思、為什麼會發生、我該怎麼一步步修好。錯誤訊息如下：〔貼上整段紅字〕

剛剛的修法我照做了還是一樣，請不要重複同一個方法。請你先幫我判斷「最可能的原因有哪幾個」，再一個一個帶我確認，找到真正原因再動手改。錯誤訊息一樣是：〔貼上整段紅字〕

我不確定這段錯誤在講哪個檔案、哪一行。請你先幫我看懂它指向哪裡，需要我提供哪些檔案或資訊你才能判斷，直接告訴我要給你什麼。

錯誤索引（60 條）

• 一、環境與安裝類 6 條
• 二、套件與相依類 5 條
• 三、語法與型別類 5 條
• 四、執行期與網路類 7 條
• 五、Git 與版本控制類 6 條
• 六、部署類 6 條
• 七、API 與金鑰類 5 條
• 八、資料庫類 5 條
• 九、AI 工具本身的卡關 10 條
• 十、AI 幫倒忙類 5 條

一、環境與安裝類

我在〔Mac／Windows〕上輸入 `node -v`，跳出 `command not found: node`。我是零基礎，請一步一步帶我確認 Node.js 有沒有裝、要怎麼裝，裝完要不要重開終端機。每一步請告訴我要在哪裡打字、打什麼。

我輸入 `python` 出現 `command not found`，但我記得好像有裝過。請幫我判斷是不是要改打 `python3`，還有怎麼確認到底裝了沒。我用的是〔Mac／Windows〕。

我啟動專案時出現 `requires Node version >=18`，但我不知道我現在是哪一版、也不知道怎麼換。請先教我怎麼查目前版本，再一步步帶我升級或切換到它要的版本。我用〔Mac／Windows〕。

我在做〔說明你剛剛在做什麼，例如 npm 全域安裝〕時出現 `permission denied`。請先告訴我這通常代表什麼、有沒有「不用硬加權限」的安全做法，再帶我操作。我不希望亂用 sudo 把系統弄壞，請提醒我風險。

我在 Windows 輸入 `〔你打的指令〕`，出現 `is not recognized as an internal or external command`。請一步步帶我確認這個程式有沒有裝、怎麼把它加進 PATH，最後要不要重開機。

我剛用〔你的安裝方式，例如 npm install -g、brew〕裝好 `〔工具名〕`，但一跑就說 `command not found`。請幫我判斷是 PATH 沒設好、還是要重開終端機、還是我呼叫的方式錯了，一步步帶我排查。

二、套件與相依類

我執行專案時出現 `Cannot find module ``'``〔它說找不到的名字〕``'`。請先判斷這是「還沒安裝」還是拼錯名字？如果要安裝，直接給我完整的安裝指令，並告訴我要在哪個資料夾裡打。

我跑 `npm`` install` 失敗，噴出一大片 `npm`` ERR!`。我把整段完整貼給你，請幫我找出「真正的關鍵那一行」是什麼、代表什麼問題，再給我對應的解法。訊息如下：〔貼上整段紅字，不要只貼第一行〕

我安裝套件時出現 `peer dependency conflict`（完整訊息如下）。請先幫我看懂是「哪兩個套件、為了哪個版本」在衝突，再告訴我最安全的解法是什麼，並提醒我硬繞過去會不會有後遺症。訊息：〔貼上整段〕

我的 `package-``lock.json`（或 `pnpm-lock.yaml`）出現 `<<<<<<<` 這種衝突標記，安裝就失敗。我是零基礎，這個檔案我看不懂也不敢亂改。請告訴我最安全的處理方式，最好是能直接重新產生一份乾淨的，一步步帶我做。

我用 `npm`` install` 裝了 `〔套件名〕`，安裝顯示成功，但我直接打它的指令卻 `command not found`。請幫我判斷它是裝在本地還是全域，還有正確的呼叫方式應該是什麼（例如是不是要用 npx 或 package.json 裡的 script）。

三、語法與型別類

我存檔後出現 `SyntaxError``: Unexpected token`，它指到〔檔名與行號，紅字裡會寫〕。請幫我看這附近是不是少了或多了標點、括號。我把那一段程式碼貼給你：〔貼上錯誤指到的那幾行〕

我遇到 `TypeError``: Cannot read properties of undefined (reading ``'``〔它說的那個名字〕``')`。這在我〔說明你剛做的動作，例如按下送出、開啟頁面〕時發生。請幫我判斷是不是某個資料還沒準備好就被用了，並教我怎麼加保護讓它不要一空就爆掉。相關程式碼：〔貼上〕

我呼叫 `〔那個名字〕` 時出現 `is not a function`。請幫我確認這個名字有沒有拼錯、是不是引入的方式不對、還是它在新版被改名了。我用的套件是〔套件名與版本，若知道〕，程式碼片段：〔貼上〕

我遇到 `ReferenceError``: ``〔那個名字〕`` is not defined`。請幫我判斷是我把名字打錯了、還是漏了宣告、還是少 import 了某個東西。這是相關程式碼：〔貼上〕

我出現 `Unexpected end of input`，它指到檔案最後。我猜是有括號或引號沒關好。請幫我檢查這個檔案的括號有沒有成對，把該補的補上。整個檔案內容如下：〔貼上整個檔案〕

四、執行期與網路類

我啟動專案時出現 `EADDRINUSE: address already in use ``:::``〔那個數字〕`。請告訴我兩條路：一是怎麼把占用這個 port 的舊程式關掉，二是怎麼改用另一個 port 啟動。我用〔Mac／Windows〕，一步步帶我。

我的網頁抓資料時，Console 出現 `blocked by CORS policy`。請用白話跟我解釋 CORS 是什麼，然後幫我判斷該改的是前端呼叫的方式，還是後端要開放權限，並分別告訴我怎麼做。我的前端跑在〔網址〕，要打的 API 在〔網址〕。

我抓資料時出現 `Failed to fetch`。請幫我一項一項排查：後端有沒有在跑、網址對不對、是不是網路或 CORS 問題。告訴我每一項要怎麼自己確認。我要打的網址是〔網址〕。

我的網頁打開是一片空白，畫面上沒有任何錯誤。請教我怎麼打開瀏覽器的開發者工具、切到 Console 分頁去看有沒有紅字，我把看到的紅字貼給你。如果 Console 是空的，也請告訴我下一步該看哪裡。

我的頁面一直轉圈、載不出來也不報錯。請幫我判斷是不是「資料請求失敗了但程式沒處理」，並教我怎麼加上「載入失敗就顯示提示」而不是一直轉。同時教我怎麼在開發者工具的 Network 分頁看那個請求是成功還失敗。相關程式碼：〔貼上〕

我呼叫後端時回 `500 Internal Server Error`。我知道這代表伺服器端出錯。請教我去哪裡看後端的錯誤紀錄（log），找出真正的錯誤那一行，我再貼給你。我的後端是〔平臺或框架名，若知道〕。

我遇到 `Maximum call stack size exceeded`。我知道這通常是「無限循環呼叫」造成的。請幫我從這段程式碼找出是哪裡在無限呼叫自己、要怎麼加上停止條件。程式碼：〔貼上你懷疑的那段〕

五、Git 與版本控制類

我合併時出現 `CONFLICT`，檔案裡有 `<<<<<<<`、`=======`、`>>>>>>>` 這些符號。我是零基礎，看不懂哪段是誰的。請幫我解讀：`=======` 上面那段是誰的、下面那段是誰的，我該保留哪個、還是兩個都要。我把整段貼給你：〔貼上含箭頭符號的那一整段〕

我 push 時出現 `Updates were rejected`，看起來是雲端有我還沒有的更新。請一步步帶我安全地先把遠端的更新拉下來、跟我的合併好，再推上去。過程中如果會有衝突，請提醒我怎麼處理。

Git 說我在 `detached HEAD` 狀態。我不太確定自己是怎麼跑到這裡的，也怕改的東西不見。請用白話解釋這是什麼狀態、我現在該怎麼安全回到正常的分支，如果我剛剛有改東西，怎麼保住它。

我不小心把〔大檔案／含密碼的檔案〕commit 進去了，還沒（或已經）push。請告訴我：一、怎麼把它從版本記錄裡移除；二、怎麼設定 `.``gitignore` 以後不再提交它；三、如果裡面有密鑰，我是不是必須立刻去把那把金鑰作廢重發。請按嚴重程度排順序帶我做。

我打 Git 指令時出現 `fatal: not a git repository`。請幫我判斷是「這個專案還沒被 Git 初始化」，還是「我站錯資料夾了」。教我怎麼確認目前在哪個資料夾、以及該怎麼做才對。

我 push 到〔GitHub／其他平臺〕時出現 `Authentication failed`。我是零基礎。請幫我判斷現在該用哪種驗證方式（密碼、存取權杖、還是 SSH 金鑰），並一步步帶我設定好。我用〔Mac／Windows〕。

六、部署類

我部署到〔平臺名〕時出現 `Build failed`。我把完整的建置紀錄（build log）貼給你，請幫我找出真正卡住的那一行、代表什麼問題、怎麼修。紀錄如下：〔貼上整段 build log，尤其是紅字附近〕

我的專案本機正常，但部署後〔某功能，例如登入、抓資料〕就壞了。我懷疑是環境變數沒設。請教我怎麼比對本機的 .env 跟部署平臺上設定的變數，找出漏掉哪些、怎麼在平臺上補齊。我用的平臺是〔平臺名〕。

我的網站首頁正常，但點進內頁或按重新整理就 404。我猜是路由沒設定好。請幫我判斷這是不是單頁應用要加的「rewrite／redirect 規則」，並告訴我在〔平臺名〕上具體要加什麼設定。我用的框架是〔框架名，若知道〕。

我部署後線上還是舊的。請先教我怎麼強制重新整理、清掉瀏覽器快取，確認不是我這邊的問題，再教我怎麼確認部署到底有沒有真的成功、以及怎麼清掉平臺的快取。我用〔平臺名〕。

我線上的〔功能名〕出現 `timed out`（逾時）。請幫我判斷是不是「這段做太多事、跑太久」，並給我兩種方向：一是怎麼讓它跑快一點，二是能不能把工作拆小或改成背景處理。我用〔平臺名〕，這段大概在做〔說明它在做什麼〕。

我本機正常，但部署時出現 `Module not found: ``〔它說找不到的名字〕`。請重點幫我檢查兩件事：一、我 import 的檔名大小寫跟實際檔名有沒有完全一致；二、這個套件有沒有被正確記進 package.json。我用〔平臺名〕。

七、API 與金鑰類

我呼叫〔服務名〕的 API 時回 `401`（或 `403`）。請先幫我分清楚這兩個的差別，再帶我一步步排查：金鑰是不是有效、有沒有正確被送出、帳號權限夠不夠。我串接的方式大概是〔簡述，例如在前端 fetch、後端呼叫〕。

我呼叫〔服務名〕時出現 `429 Too Many Requests`。請幫我判斷是不是我的程式在短時間內打太多次（例如迴圈裡重複呼叫），並教我怎麼加上稍等再重試的機制，避免一直撞牆。相關程式碼：〔貼上〕

我串接〔服務名〕一直失敗，感覺是 API 金鑰的問題。請帶我逐項檢查：金鑰有沒有複製完整（頭尾有沒有多空格）、放的環境變數名稱對不對、以及這個服務前端跟後端該用的金鑰是不是不同把。

我不小心把〔服務名〕的 API 金鑰外洩了（寫在程式碼裡推上了公開倉庫）。請按照緊急程度帶我處理：一、立刻去哪裡把這把金鑰作廢、重新產生一把；二、怎麼把金鑰改放到環境變數、不再寫死在程式裡；三、怎麼設定 .gitignore 避免再犯。

我呼叫〔服務名〕的 API 一直逾時。請幫我排查：是對方服務本身慢／掛了，還是我這邊網址設定有問題，還是我一次要太多資料。教我怎麼分別確認，以及怎麼加上「逾時重試」讓它更穩。

八、資料庫類

我的程式出現 `connection refused`，連不上資料庫。請帶我逐項排查：資料庫服務有沒有在跑、連線設定（主機、埠號、帳號、密碼、資料庫名稱）對不對、是不是被防火牆擋。我用的資料庫是〔資料庫種類，例如 PostgreSQL、MySQL 或 Supabase〕。

我跑資料庫 migration 時失敗，訊息如下。請幫我看懂它卡在哪一步、為什麼，最安全的處理方式是什麼（尤其我不想弄丟現有資料）。訊息：〔貼上整段〕。我用〔資料庫或工具名〕。

我遇到程式跟資料庫對不上的問題（它說某欄位不存在／型別不符，但我以為改過了）。請幫我判斷是不是「我改了定義但沒同步到資料庫」，並帶我確認兩邊目前的實際結構、怎麼把它們對齊。我用〔工具名，例如 Prisma、Drizzle、Supabase〕。

我執行這段 SQL 時出現 `syntax error at or near ``"``〔它指的那個字〕``"`。請幫我找出文法錯在哪、改好給我。我用的資料庫是〔種類〕。這是我的 SQL：〔貼上整段查詢〕。

我在〔新增／刪除〕資料時出現 `〔``unique``／``foreign`` key``〕`` constraint` 衝突。請用白話解釋這條規矩在保護什麼，並幫我判斷正確的做法是什麼（例如是不是該先檢查有沒有重複、或先處理關聯的資料）。完整訊息：〔貼上〕。

九、AI 工具本身的卡關

我們這個對話已經很長了，我覺得你開始忘記前面的東西。請幫我把目前的進度、已經做了什麼決定、還沒做什麼、關鍵的檔案和設定，總結成一段交接筆記，我要拿它到新對話重新開始。

你剛剛改的檔案超出我要求的範圍了。我只要你改〔指定的那個檔案或功能〕，其他一律不要動。請先列出你剛剛總共改了哪些檔案，把不該動的那些還原回去，之後每次動手前先跟我說「你打算改哪些檔案」，等我同意再做。

停。我們已經來回改了好幾次都沒好，請不要再直接改程式了。請你退一步，先列出這個問題最可能的 2 到 3 個根本原因，我們一個一個來確認，找到真正的病根再動手。也請你老實說，是不是有哪個假設你一直沒驗證。

你說修好了，但我這邊測試還是不行。請不要只是「認為」好了，請你實際去執行／驗證，並把「你怎麼驗證的、看到什麼結果」告訴我。如果你沒辦法親自驗證，請老實說「我沒辦法驗證，需要你幫我確認以下這幾點」，而不是直接說完成。

你剛剛叫我用的〔套件／指令／功能名〕，我裝／用了之後說不存在，我也查不到。請你確認這東西是不是真的存在、有沒有官方文件可查。如果你不確定，請明講「我不確定」，我們去找真正存在的替代方案，不要用猜的。

你一直停下來問我同不同意，我想讓流程順一點。請告訴我：哪些「安全、可逆」的動作我可以一次性允許、不用每次問；哪些「有風險」的動作（例如刪檔、部署、動到金鑰）務必每次都先問我。幫我拿捏這個界線。

我想用的〔MCP 工具名〕連不上，相關功能都不能用。請帶我逐項排查：設定檔有沒有寫對、需要的金鑰有沒有填、那個服務有沒有在跑、要不要重啟工具才生效。我用的是〔Claude Code／Codex／Antigravity〕，錯誤訊息（若有）：〔貼上〕。

你說已經〔push／部署〕成功，但我去看根本沒更新。請你重新執行一次，並把「指令的完整回傳訊息」原封不動貼給我，我們一起看它到底是成功還是失敗。不要只跟我說結論，要給我證據。

你說找不到〔檔名〕，但它確實存在。請先告訴我你現在認為的「工作目錄」是哪裡，再幫我確認這個檔案的正確完整路徑。我們先把「你站在哪、檔案在哪」對齊，再繼續。

我碰到用量／額度限制了。在等額度回復的這段時間，請幫我把目前的進度和接下來的計畫整理成一份筆記，這樣我等一下（或換個工具）可以無縫接上。另外也給我幾個省用量的建議，避免太快又撞上限。

十、AI 幫倒忙類

你加新功能之後，我發現〔原本的某功能〕不見／壞了。請比對你這次的改動，找出是不是把某段原本有用的程式刪掉或改壞了，把它恢復回來。之後請記住：沒有我的同意，不要刪除任何現有功能，就算你覺得它沒用。

這個需求其實很簡單，你做得太複雜了，我看不懂也維護不了。請用最簡單、最少檔案或最少套件的方式重做一次，目標是我這個零基礎的人也能看懂每一步。我真正要的只是〔一句話講清楚最小需求〕。

剛剛這一連串改動把東西弄壞了，我不想再一點一點修。請幫我把這次對話所做的所有改動整組還原，回到我們開始改之前那個能正常運作的版本。還原後先跟我確認一切正常，我們再重新規劃。

不用道歉，我要的是解決。請你先停下來，用一句話清楚說明「這個問題目前真正的卡點是什麼」，還有「你接下來要試的方法，跟前面失敗的那些有什麼不同」。如果你其實也不確定，就直說，我們一起換個方向找資料。

這不是我要的。在你繼續做之前，請先用你自己的話，把你理解我要的是什麼，複述一遍給我確認。我真正要的是〔用一兩句話重講一次，愈具體愈好，最好舉個例子〕。等我說對了，你再動手。

其他常見問題

沒找到你的問題？