Claude Code 啟動卡住：v2.1.311 的 CLAUDE.md 長清單修正

2026-10-27

AI

Claude Code

/

AI

/

開發工具

/

疑難排解

Claude Code 在啟動、讀檔或編輯後長時間卡住，未必是模型還在思考。v2.1.311 官方 release明確列出一項修正：CLAUDE.md 含非常長的清單項目時，可能在這些時點發生長時間凍結。

先核對實際執行版本，再檢查載入的指令檔；不要直接清空正式 CLAUDE.md。 官方沒有在這條 release note 提供觸發字元門檻，因此不能用「超過某個行長」直接判定根因。這篇提供的是縮小範圍的方法，沒有在 Claude CLI 重現該缺陷。

先區分啟動凍結與請求失敗#

v2.1.311 發布於 2026-10-26 21<51> UTC，台灣時間為 10 月 27 日 05<51>。適合對照這條修正的症狀，是啟動或讀寫檔案時長時間失去回應，且環境內有很長的 CLAUDE.md 清單項目；僅看到 HTTP 429、OAuth 失敗或模型錯誤，不能直接歸到同一原因。

在出問題的終端機執行以下診斷命令，記下版本與可執行檔位置；這些是讀者操作步驟，本文未執行 Claude CLI：

1
command -v claude
2
claude --version
3
claude doctor

若從 IDE、排程或另一台主機啟動，也要分別確認其實際版本。更新一個 shell 的安裝，不代表其他啟動入口已換成同一份程式。依原本的安裝方式更新後，重新啟動受影響的程序，再重跑原本卡住的最小操作。

若症狀是 API 錯誤，先依 Claude Code 官方事故與本機問題的分流方法檢查，不必為了這項修正刪除登入資訊或重設 token。

用行號與長度找檢查起點，不輸出指令內容#

下面的 Python 3 程式只讀取你明確指定的 UTF-8 檔案，列出最長的五個實體行：不掃家目錄、不追蹤 import，也不列印行內文字。存成 instruction-lengths.py，在終端機執行 python3 instruction-lengths.py ./CLAUDE.md；多份檔案可接在後面。

1
import json
2
import sys
3
from pathlib import Path
4

5
if len(sys.argv) < 2:
6
    raise SystemExit('usage: python3 instruction-lengths.py FILE [FILE ...]')
7

8
for index, name in enumerate(sys.argv[1:], start=1):
9
    path = Path(name)
10
    lines = path.read_text(encoding='utf-8').splitlines()
11
    ranked = sorted(
12
        ((len(line), number) for number, line in enumerate(lines, start=1)),
13
        key=lambda item: (-item[0], item[1]),
14
    )[:5]
15
    print(json.dumps({
16
        'file_index': index,
17
        'bytes': path.stat().st_size,
18
        'lines': len(lines),
19
        'longest_lines': [
20
            {'line': number, 'characters': length}
21
            for length, number in ranked
22
        ],
23
    }, ensure_ascii=False))

file_index 對應輸入參數的順序，因此輸出也不含路徑。它計算 Unicode 字元數，不是 token 數，也不是 Markdown parser：跨行清單、巢狀結構與 import 展開不會合併計算，最長行也可能只是一般段落。這是定位人工檢閱位置的工具，不是缺陷偵測器。 檔案不存在或不是有效 UTF-8 時會停止並顯示例外；錯誤訊息可能含路徑，分享前仍需檢查。

內容維護流程於 2026-10-27 用含長單行清單、中文、換行、空檔案及同長度行的人工 fixture 執行這段程式，確認排序、行號與輸出沒有帶入正文。這只驗證檢查器，不能證明哪些文字會讓 Claude Code 凍結。

比較副本時，只改一個變因#

官方 memory 文件說明 CLAUDE.md 可載入其他檔案，且 session 會讀取不同層級的指令。只查看 repository 根目錄那一份，未必已涵蓋全部來源。session 能開啟時，用 /context 核對實際載入項目；/memory 可列出並開啟相關位置，但清單也可能包含尚未存在的檔案位置，不能把它當成本次全部已載入的證據。

在不含正式憑證的可拋棄副本，保留指令檔原始版本，對照同一個 CLI、工作目錄、設定與最小唯讀操作。先測原副本，再只把可疑長清單拆成較短段落或清單項目，保留原本的規則意思，觀察啟動與讀檔是否仍會卡住。不要同時換模型、移除所有 MCP、清記憶與刪指令檔，否則改善後也無法知道哪項變更有關。

這份比較流程尚未執行。副本的路徑會改變 project 設定或記憶來源時，結果只能作線索；應記下實際載入清單與差異。不要為了在舊版復現而降級正式環境，也不要把「空目錄可以開」當成已證明原專案哪一段有錯。