Claude Code 是社區(qū)討論度很高的一款 AI 編程輔助工具典型形態(tài)是駐留在終端里的開發(fā)助手。它跟普通聊天窗口最大的區(qū)別是能讀取項(xiàng)目目錄、查看文件、執(zhí)行命令再根據(jù)結(jié)果繼續(xù)修改。整個(gè)工作流更接近“真人開發(fā)的循環(huán)”讀代碼、改代碼、跑命令、看輸出、修問(wèn)題。如果你正在做 AI 大模型應(yīng)用開發(fā)或者平時(shí)要在本地倉(cāng)庫(kù)里反復(fù)改代碼這個(gè)工具值得花一個(gè)下午跑通。這篇內(nèi)容會(huì)按實(shí)際使用順序拆先確認(rèn)它適合哪些場(chǎng)景再整理安裝環(huán)境然后完成登錄認(rèn)證接著從單個(gè)任務(wù)跑到批量任務(wù)最后補(bǔ)上配置技巧和問(wèn)題排查。全程不追求把功能列表背一遍重點(diǎn)是怎么在你的機(jī)器上穩(wěn)定跑起來(lái)。很多教程喜歡把“效果好”“省 token”放在最前面。我反倒建議先把關(guān)注點(diǎn)放在環(huán)境、輸入輸出格式和失敗處理上。下面直接從環(huán)境檢查開始。1. 先確認(rèn)它到底適合放在工作流的哪個(gè)位置1.1 它不是又一個(gè)聊天框而是“讀代碼—改代碼—跑命令”的循環(huán)Claude Code 的核心形態(tài)是在終端里啟動(dòng)一個(gè)交互式會(huì)話。你輸入自然語(yǔ)言需求它讀取項(xiàng)目文件給出修改建議或命令然后你確認(rèn)執(zhí)行。它和 Web 聊天產(chǎn)品的最大差別是它擁有當(dāng)前目錄這個(gè)上下文。也就是說(shuō)它可以做到先看目錄里有哪些文件再判斷改哪里。讀取指定文件內(nèi)容結(jié)合項(xiàng)目結(jié)構(gòu)給出修改方案。執(zhí)行命令比如跑測(cè)試、運(yùn)行腳本、查看結(jié)果。根據(jù)命令輸出繼續(xù)調(diào)整代碼而不是讓你反復(fù)復(fù)制粘貼報(bào)錯(cuò)信息。這套流程對(duì)本地項(xiàng)目、腳本開發(fā)、批量文件處理、多文件重構(gòu)非常友好。因?yàn)樗恍枰看味荚诹奶齑翱诶镏匦抡迟N上下文項(xiàng)目路徑本身就成了對(duì)話的一部分。1.2 和 IDE 插件、Web 聊天相比差異在哪不少人是先接觸 IDE 里的 AI 插件再接觸 Claude Code。兩者體驗(yàn)并不相同。對(duì)比項(xiàng)終端 AI 助手IDE AI 插件Web 聊天工作位置項(xiàng)目目錄 / 命令行編輯器側(cè)邊欄或面板瀏覽器擅長(zhǎng)場(chǎng)景多文件、命令執(zhí)行、批量任務(wù)、項(xiàng)目級(jí)改造當(dāng)前文件補(bǔ)全、代碼解釋、局部修改通用問(wèn)答、方案設(shè)計(jì)、代碼片段上手難度需要一點(diǎn)命令行基礎(chǔ)入門較低最低上下文來(lái)源當(dāng)前目錄、文件讀取、命令輸出當(dāng)前文件、選中代碼手動(dòng)粘貼典型用途項(xiàng)目級(jí)腳本、重構(gòu)、命令行閉環(huán)寫單文件、快速補(bǔ)全找思路、寫初版這里沒有高低之分。IDE 插件更適合邊寫邊補(bǔ)Web 聊天更適合做方案預(yù)演。Claude Code 的優(yōu)勢(shì)在于當(dāng)任務(wù)需要跨多個(gè)文件、需要看命令結(jié)果、需要反復(fù)調(diào)整時(shí)它更接近一個(gè)“能自己動(dòng)手的臨時(shí)同事”。1.3 哪些場(chǎng)景值得用哪些場(chǎng)景別強(qiáng)搬值得用的場(chǎng)景你有一個(gè)完整可運(yùn)行的項(xiàng)目想批量調(diào)整多個(gè)文件的代碼。你想寫一個(gè) CLI 小工具需要不斷運(yùn)行命令驗(yàn)證。你要整理一堆文件比如重命名、格式轉(zhuǎn)換、批量替換。你想讓 AI 先讀懂項(xiàng)目結(jié)構(gòu)再回答“這個(gè)模塊應(yīng)該怎么改”。不建議硬搬的場(chǎng)景只是問(wèn)一個(gè)概念、一段簡(jiǎn)單代碼直接用 Web 聊天更快。項(xiàng)目里沒有測(cè)試也沒有版本管理AI 改完你無(wú)法判斷有沒有破壞原有功能。代碼庫(kù)里有數(shù)據(jù)庫(kù)密碼、密鑰、敏感配置AI 工具讀取后容易產(chǎn)生額外風(fēng)險(xiǎn)。面向用戶的線上生產(chǎn)環(huán)境沒有經(jīng)過(guò)評(píng)審就直接讓 AI 改風(fēng)險(xiǎn)很高。先判斷場(chǎng)景再?zèng)Q定是否安裝能避免“裝完發(fā)現(xiàn)根本用不上”的情況。2. 安裝前把運(yùn)行環(huán)境整理干凈能省下后面一大半報(bào)錯(cuò)2.1 先看 Node.js 和 npm 版本再動(dòng)手安裝Claude Code 依賴 Node.js 環(huán)境運(yùn)行安裝通常通過(guò) npm 完成。所以第一步不是直接執(zhí)行安裝命令而是先確認(rèn) Node.js 和 npm 是否可用。在終端執(zhí)行node -v npm -v如果輸出類似v20.11.0、10.2.4說(shuō)明環(huán)境基本可用。如果提示“不是內(nèi)部或外部命令”說(shuō)明 Node.js 沒有安裝或者安裝后沒有配置 PATH。不同版本對(duì) Node.js 的最低要求可能會(huì)變。穩(wěn)妥的方法是先使用 Node.js 的 LTS 版本避免用太老的版本安裝最新 CLI。判斷標(biāo)準(zhǔn)很簡(jiǎn)單安裝時(shí)報(bào)版本不兼容優(yōu)先升級(jí) Node.js而不是去降低 CLI 版本。2.2 終端環(huán)境PowerShell、CMD、Shell 和編碼問(wèn)題Windows 上最容易出問(wèn)題的不是安裝本身而是終端環(huán)境。如果你在 PowerShell 里提示權(quán)限不足先檢查執(zhí)行策略Get-ExecutionPolicy如果返回Restricted可以調(diào)整為當(dāng)前用戶允許運(yùn)行本地腳本Set-ExecutionPolicy -Scope CurrentUser RemoteSigned這條命令的含義是允許當(dāng)前用戶運(yùn)行本地腳本遠(yuǎn)程下載的腳本必須帶簽名。它不是關(guān)閉安全機(jī)制只是放行本地開發(fā)腳本。如果你經(jīng)常遇到中文亂碼終端編碼也要處理chcp 65001這會(huì)把控制臺(tái)代碼頁(yè)切換為 UTF-8。Windows 下默認(rèn)的代碼頁(yè)經(jīng)常導(dǎo)致中文文件名、中文輸出顯示成亂碼后面排查時(shí)不要忽略這個(gè)點(diǎn)。macOS 或 Linux 上重點(diǎn)檢查默認(rèn) Shell 的配置文件比如~/.bashrc、~/.zshrc。如果安裝后發(fā)現(xiàn)命令找不到很可能是 PATH 沒有重新加載重開終端就能解決。2.3 賬號(hào)認(rèn)證、API Key 和密鑰安全意識(shí)Claude Code 使用前需要完成賬號(hào)認(rèn)證。常見方式有兩種使用訂閱賬號(hào)通過(guò)授權(quán)流程登錄。使用 API Key在配置中指定密鑰。具體方式以你當(dāng)前使用版本的官方流程為準(zhǔn)不要照搬老教程的截圖。這里必須強(qiáng)調(diào)一點(diǎn)API Key 本質(zhì)上是憑證泄露后別人就能消耗你的額度甚至訪問(wèn)你能訪問(wèn)的數(shù)據(jù)。建議把密鑰放在環(huán)境變量或本地配置文件中不要直接寫進(jìn)命令參數(shù)。更不要把它提交到 Git 倉(cāng)庫(kù)。如果你在項(xiàng)目里用.env文件管理環(huán)境變量大致寫法是ANTHROPIC_API_KEY你的密鑰然后把.env加入.gitignoreecho .env .gitignore先保證密鑰不會(huì)進(jìn)倉(cāng)庫(kù)再開始體驗(yàn)各種功能。2.4 建一個(gè)專門的測(cè)試目錄別在系統(tǒng)路徑里亂跑第一次使用不要直接在一個(gè)龐大的倉(cāng)庫(kù)里運(yùn)行。很多新手把 Claude Code 啟動(dòng)在項(xiàng)目根目錄AI 助手會(huì)嘗試讀取海量文件既慢又容易出錯(cuò)還不確定會(huì)不會(huì)誤改東西。建議單獨(dú)創(chuàng)建一個(gè)測(cè)試目錄mkdir -p ~/projects/claude-playground cd ~/projects/claude-playground路徑盡量用英文避免空格、中文和特殊符號(hào)。雖然很多環(huán)境能處理但一旦出現(xiàn)路徑解析問(wèn)題排查成本會(huì)上升。這個(gè)目錄里放一個(gè)小項(xiàng)目或者干脆先放幾個(gè)測(cè)試文件用來(lái)驗(yàn)證安裝和認(rèn)證是否成功。3. 從安裝到首次對(duì)話完整實(shí)操流程3.1 安裝 CLI 并驗(yàn)證版本環(huán)境確認(rèn)正常后安裝 CLI。常見的安裝方式是通過(guò) npm 全局安裝npm install -g anthropic-ai/claude-code注意包名不要打錯(cuò)。安裝完成后先驗(yàn)證版本claude --version如果輸出版本號(hào)說(shuō)明安裝成功。如果提示命令找不到不要急著重裝。優(yōu)先按這個(gè)順序排查關(guān)閉當(dāng)前終端重新打開一個(gè)新終端。確認(rèn) npm 全局 bin 目錄是否在系統(tǒng) PATH 中。用npm config get prefix查看全局安裝目錄檢查該目錄是否被終端識(shí)別。很多“安裝完但 claude 命令不存在”的問(wèn)題基本都是 PATH 沒有生效而不是 CLI 本身有問(wèn)題。3.2 完成認(rèn)證跑通第一次對(duì)話安裝成功后啟動(dòng)claude首次運(yùn)行會(huì)進(jìn)入登錄或授權(quán)流程。終端里可能給出授權(quán)鏈接也可能直接彈出瀏覽器頁(yè)面。按提示完成授權(quán)后回到終端應(yīng)該能看到交互式會(huì)話入口。驗(yàn)證是否跑通的標(biāo)準(zhǔn)很簡(jiǎn)單在會(huì)話里輸入一句普通命令比如 “列出當(dāng)前目錄里的文件”看它能否用自然語(yǔ)言回復(fù)并給出相關(guān)操作建議。如果提示認(rèn)證失敗優(yōu)先檢查API Key 是否復(fù)制完整有沒有多余空格。授權(quán)鏈接是否已經(jīng)過(guò)期過(guò)期就重新發(fā)起認(rèn)證。當(dāng)前終端是否在正確的項(xiàng)目目錄下避免和另一個(gè)項(xiàng)目的配置沖突。3.3 在 VS Code 里聯(lián)動(dòng)內(nèi)置終端是第一選擇很多人在問(wèn)“VSCode 配置 Claude Code 怎么弄”。我的建議是先不要急著裝擴(kuò)展直接用 VS Code 的內(nèi)置終端。打開 VS Code按快捷鍵呼出終端面板然后運(yùn)行claude這樣做的好處是終端會(huì)自動(dòng)繼承當(dāng)前項(xiàng)目的工作目錄。文件樹、編輯器、終端在同一窗口內(nèi)查看代碼和讓 AI 改代碼切換成本很低。不需要額外學(xué)習(xí)擴(kuò)展配置減少一個(gè)不穩(wěn)定因素。等終端模式用熟了再考慮 VS Code 生態(tài)里的可視化擴(kuò)展。擴(kuò)展能提供側(cè)邊欄、對(duì)話面板等入口但底層依賴的 CLI 能力是一樣的。如果擴(kuò)展安裝后出現(xiàn)權(quán)限、路徑、重復(fù)登錄問(wèn)題先回到內(nèi)置終端驗(yàn)證多數(shù)問(wèn)題能快速定位。3.4 最小任務(wù)先列清單再動(dòng)手改文件跑通對(duì)話后不要直接就讓它改代碼。第一個(gè)任務(wù)建議選一個(gè)沒有破壞性的小需求。比如目錄里有幾個(gè).log文件需求是把它們按修改時(shí)間重命名。你可以這樣描述幫我寫一個(gè) Python 腳本把當(dāng)前目錄下所有 .log 文件按修改時(shí)間重命名格式為 20260301_001.log。 先不要執(zhí)行修改只列出文件清單和重命名后的對(duì)應(yīng)關(guān)系。關(guān)鍵在于“先不要執(zhí)行修改”。這樣做的原因是AI 理解的“重命名規(guī)則”和你想的規(guī)則可能不完全一樣。先讓它輸出計(jì)劃你檢查一遍再讓它執(zhí)行能避免一上來(lái)就把文件搞亂。運(yùn)行完腳本后手動(dòng)檢查文件名是否符合預(yù)期。這個(gè)最小任務(wù)跑通說(shuō)明安裝、認(rèn)證、項(xiàng)目文件讀取、命令執(zhí)行這整條鏈路都正?？梢赃M(jìn)入更復(fù)雜的實(shí)戰(zhàn)。4. 代碼實(shí)戰(zhàn)從單文件工具到項(xiàng)目級(jí)改造4.1 寫需求時(shí)把輸入、輸出、約束、驗(yàn)收標(biāo)準(zhǔn)都寫清楚Claude Code 雖然能讀項(xiàng)目但如果不把需求邊界說(shuō)清楚它會(huì)做出“看起來(lái)很合理實(shí)際完全不對(duì)”的事情。我一般會(huì)按這個(gè)模板描述需求任務(wù)目標(biāo)把 src/ 下的全部 .txt 文件轉(zhuǎn)換為 .md并保留原文件名。 輸入目錄src/ 輸出目錄docs/ 約束 - 不要修改 src/ 下其他格式的文件。 - 不要?jiǎng)h除原文件。 - 轉(zhuǎn)換后保留原標(biāo)題中的一級(jí)標(biāo)題。 驗(yàn)收標(biāo)準(zhǔn)每個(gè) .txt 對(duì)應(yīng)生成一個(gè)同名 .md內(nèi)容中一級(jí)標(biāo)題不變。輸入輸出寫清楚AI 才能選擇正確的文件范圍。約束寫清楚才能避免它順手把其他文件也改了。驗(yàn)收標(biāo)準(zhǔn)寫清楚你才知道什么時(shí)候算完成。這一步看著啰嗦但能大幅減少后續(xù)返工。4.2 控制上下文別把整個(gè)倉(cāng)庫(kù)一次性塞給助手Claude Code 能讀取項(xiàng)目文件但不代表你應(yīng)該讓它讀所有文件。項(xiàng)目里常有node_modules、dist、build、.git這類目錄體積大且沒有參考價(jià)值。實(shí)戰(zhàn)中我發(fā)現(xiàn)一個(gè)常見浪費(fèi)就是讓助手待在大倉(cāng)庫(kù)根目錄它為了理解任務(wù)會(huì)翻大量無(wú)關(guān)文件。更穩(wěn)妥的做法是在相關(guān)模塊的子目錄里啟動(dòng)會(huì)話縮小探索范圍。在項(xiàng)目說(shuō)明文件里寫清楚目錄結(jié)構(gòu)、構(gòu)建命令和“不要?jiǎng)幽男┠夸洝?。需要分析某個(gè)文件時(shí)直接告訴它文件路徑而不是讓它漫無(wú)目的地全庫(kù)搜索。上下文越聚焦回答質(zhì)量越高token 消耗也越低。4.3 批量任務(wù)先小樣本跑通再全量執(zhí)行批量處理是 Claude Code 的高價(jià)值場(chǎng)景但它也是翻車重災(zāi)區(qū)。很多任務(wù)卡住、失敗、輸出錯(cuò)亂并不是 AI 能力不行而是你一次性把整個(gè)目錄交給它處理中間沒有檢查點(diǎn)。建議把批量任務(wù)拆成四個(gè)階段準(zhǔn)備 3 到 5 個(gè)樣例文件先跑單條流程。檢查樣例輸出的文件名、內(nèi)容、格式是否符合預(yù)期。確認(rèn)無(wú)誤后再讓助手遍歷完整目錄。全量跑完后用git status或文件列表檢查變更范圍。如果全量執(zhí)行時(shí)出現(xiàn)部分失敗不要直接重跑整個(gè)目錄。優(yōu)先看日志或輸出結(jié)果找出失敗文件的特點(diǎn)再單獨(dú)處理。批量任務(wù)的正確姿勢(shì)是“失敗重試單條”不是“無(wú)腦重跑全量”。判斷批量任務(wù)是否成功的標(biāo)準(zhǔn)包括輸出文件數(shù)量是否等于預(yù)期輸入數(shù)量。文件名是否按規(guī)則生成。內(nèi)容是否完整有沒有截?cái)嗷蛘`替換。是否動(dòng)了約束范圍之外的文件。4.4 把 AI 生成代碼納入 Git 評(píng)審流程讓 AI 改代碼不是終點(diǎn)提交前必須人工檢查。我已經(jīng)習(xí)慣把 AI 生成的內(nèi)容當(dāng)作“候選人代碼”不是“最終答案”。具體流程git diff先看改動(dòng)內(nèi)容確認(rèn)只有目標(biāo)文件被修改。然后看關(guān)鍵邏輯確認(rèn)沒有引入未定義的變量、循環(huán)邊界錯(cuò)誤或明顯安全問(wèn)題。最后跑一遍測(cè)試或手動(dòng)驗(yàn)證。確認(rèn)無(wú)誤后再提交。如果項(xiàng)目沒有 Git也沒有任何版本管理建議先執(zhí)行g(shù)it init再開始讓 AI 改代碼。否則改壞了很難退回。5. 長(zhǎng)期使用時(shí)的配置、省 Token 與擴(kuò)展思路5.1 項(xiàng)目級(jí)記憶文件把項(xiàng)目約定沉淀下來(lái)Claude Code 在讀項(xiàng)目時(shí)可以借助項(xiàng)目說(shuō)明文件理解上下文。很多項(xiàng)目會(huì)在根部放一個(gè)類似CLAUDE.md的文件用來(lái)描述項(xiàng)目結(jié)構(gòu)和約定。這是一個(gè)很值得長(zhǎng)期維護(hù)的文件。內(nèi)容可以包括項(xiàng)目目錄結(jié)構(gòu)。構(gòu)建、測(cè)試、運(yùn)行命令。代碼風(fēng)格要求。禁止修改的目錄和文件。常見任務(wù)的處理流程。比如# 項(xiàng)目說(shuō)明 ## 目錄結(jié)構(gòu) - src/ 源碼目錄 - docs/ 文檔目錄 - scripts/ 工具腳本 ## 常用命令 - npm run dev 啟動(dòng)開發(fā)環(huán)境 - npm test 運(yùn)行測(cè)試 ## 注意 - 不要修改 dist/ 目錄它是構(gòu)建產(chǎn)物。 - 不要提交 .env 文件。有了這份文件每次啟動(dòng)會(huì)話時(shí)助手能更快理解“這是個(gè)什么項(xiàng)目”“該用什么命令”。對(duì)于維護(hù)周期長(zhǎng)的項(xiàng)目收益很明顯。5.2 Skills 和自定義指令等基礎(chǔ)流程穩(wěn)定后再加社區(qū)里已經(jīng)開始討論 Claude Code 的 Skills 這類擴(kuò)展能力。簡(jiǎn)單理解Skills 是一組可復(fù)用的指令或工具定義可以讓你把常用的操作流程封裝起來(lái)減少重復(fù)描述。但我不建議新手在一開始就折騰這個(gè)。原因很簡(jiǎn)單你還沒搞清基礎(chǔ)交互邏輯就疊加自定義指令出問(wèn)題時(shí)很難判斷是項(xiàng)目配置問(wèn)題、模型理解問(wèn)題還是 Skills 定義問(wèn)題。我的建議是先滿足這幾個(gè)條件再考慮基礎(chǔ)安裝、認(rèn)證、單任務(wù)已經(jīng)穩(wěn)定跑通。已經(jīng)有至少一個(gè)項(xiàng)目的 Claude Code 實(shí)戰(zhàn)經(jīng)驗(yàn)。你明確知道哪些流程是高頻、可復(fù)用、值得固化的。Skills 的格式、目錄和加載方式會(huì)隨版本調(diào)整落地前一定要以你當(dāng)前版本的官方文檔為準(zhǔn)不要照搬網(wǎng)上的舊配置。5.3 Token 消耗怎么控制任務(wù)拆小、聚焦目錄、縮短會(huì)話省 token 的本質(zhì)是減少不必要的上下文而不是讓 AI 少寫代碼。幾個(gè)有效做法任務(wù)拆小。一個(gè)會(huì)話只完成一個(gè)目標(biāo)跑完就結(jié)束不要為了省事把十件事塞進(jìn)一段對(duì)話。限定目錄和文件。明確告訴它只讀哪些路徑不要全庫(kù)掃描。讓助手輸出 diff而不是輸出整個(gè)文件內(nèi)容。改動(dòng)范圍大時(shí)diff 可讀性更高也更省 token。長(zhǎng)會(huì)話及時(shí)斷開。對(duì)話越長(zhǎng)歷史上下文越多后續(xù)請(qǐng)求消耗越大還容易偏離主題。輸出重定向到日志文件時(shí)避免把超大輸出全部打回終端。判斷 token 是否浪費(fèi)有一個(gè)簡(jiǎn)單標(biāo)準(zhǔn)看每次請(qǐng)求里到底帶了多大上下文。如果只是一個(gè)小改動(dòng)卻讓 AI 讀取了十個(gè)無(wú)關(guān)文件那就是浪費(fèi)。5.4 本地模型服務(wù)接入的邊界社區(qū)里有人會(huì)把 Claude Code 接到 Ollama 這類本地模型服務(wù)實(shí)現(xiàn)完全本地運(yùn)行。這個(gè)思路可以實(shí)驗(yàn)但要注意邊界。Claude Code 能不能連本地模型取決于它是否支持自定義模型接口。如果版本支持按官方文檔配置模型地址和模型名即可。如果不支持不要為了接入而繞來(lái)繞去。接口協(xié)議、上下文長(zhǎng)度、工具調(diào)用能力和權(quán)限模型都可能不一致強(qiáng)行適配容易得到不可預(yù)期的結(jié)果。我的判斷是本地模型接入更適合學(xué)習(xí)和實(shí)驗(yàn)。正式項(xiàng)目里我傾向于使用官方支持的模型服務(wù)這樣可以保證日志、權(quán)限、失敗重試都處于可控范圍。判斷本地模型是否可用先做最小文本任務(wù)比如“讀取當(dāng)前目錄文件并生成清單”。如果這種基礎(chǔ)任務(wù)都不穩(wěn)定就不要指望它能完成復(fù)雜項(xiàng)目改造。6. 常見問(wèn)題排查順序先看日志再改配置6.1 啟動(dòng)失敗命令不存在、權(quán)限不足、版本不匹配現(xiàn)象輸入claude提示不是內(nèi)部或外部命令。排查順序重開一個(gè)新終端排除 PATH 未刷新問(wèn)題。執(zhí)行which claude或Get-Command claude確認(rèn)命令路徑是否可識(shí)別。檢查 Node.js 版本確認(rèn)是否滿足當(dāng)前 CLI 要求。檢查 npm 全局目錄是否在系統(tǒng) PATH 中。如果命令路徑存在但啟動(dòng)報(bào)權(quán)限錯(cuò)誤檢查當(dāng)前用戶是否有執(zhí)行權(quán)限。不要直接使用管理員權(quán)限強(qiáng)行運(yùn)行這會(huì)給后續(xù)文件讀寫帶來(lái)權(quán)限混亂。6.2 安裝報(bào)錯(cuò)npm 日志、緩存、執(zhí)行策略現(xiàn)象npm install -g anthropic-ai/claude-code執(zhí)行到一半失敗或提示權(quán)限錯(cuò)誤。先把報(bào)錯(cuò)信息完整復(fù)制出來(lái)很多問(wèn)題一眼就能看出原因。常見情況包括Node.js 版本過(guò)舊。npm 緩存異常導(dǎo)致拉取失敗。PowerShell 執(zhí)行策略限制腳本運(yùn)行。當(dāng)前用戶沒有全局安裝目錄的寫入權(quán)限。排查順序重啟終端再執(zhí)行一次安裝。查看 npm 日志日志里會(huì)寫明失敗步驟。確認(rèn)執(zhí)行策略必要時(shí)按前面提到的方式調(diào)整為RemoteSigned。不要一上來(lái)就清緩存、刪目錄。只有日志明確提示緩存損壞時(shí)才考慮。6.3 中文亂碼終端編碼、輸出重定向、文件編碼亂碼最常見的原因不是 AI 模型問(wèn)題而是終端和文件編碼不一致。排查順序在終端執(zhí)行chcp 65001切到 UTF-8 代碼頁(yè)。確認(rèn)輸出重定向時(shí)使用 UTF-8 編碼而不是系統(tǒng)默認(rèn)編碼。檢查腳本文件本身是否以 UTF-8 保存尤其是 Windows 上常見的 GBK 默認(rèn)保存。查看 VS Code 的編碼設(shè)置確保終端和編輯器編碼一致。如果中文文件名在腳本執(zhí)行后變成亂碼優(yōu)先檢查重定向和腳本保存編碼不要先懷疑 AI 能力。6.4 任務(wù)卡住或輸出異常資源占用、輸入格式、權(quán)限現(xiàn)象Claude Code 一直沒有輸出或者輸出明顯不完整。排查順序查看 CPU、內(nèi)存、磁盤占用排除資源不足。檢查輸入文件格式和編碼有些內(nèi)容看起來(lái)正常實(shí)際是損壞或特殊編碼。檢查輸出目錄是否有寫權(quán)限。查看歷史上下文是否過(guò)長(zhǎng)任務(wù)復(fù)雜時(shí)可以結(jié)束會(huì)話重新開始。檢查是否在錯(cuò)誤的目錄運(yùn)行導(dǎo)致助手找不到目標(biāo)文件。這里最重要的原則是先看日志再改參數(shù)。不要因?yàn)橐淮慰ㄗ【童偪裾{(diào)并發(fā)、改模型配置那樣只會(huì)讓問(wèn)題更難定位。6.5 安全紅線密鑰、權(quán)限和不明命令使用這類工具時(shí)安全意識(shí)必須跟上。三個(gè)底線不要碰不要向會(huì)話暴露 API Key、數(shù)據(jù)庫(kù)密碼、云服務(wù)密鑰。不要讓 AI 以過(guò)高權(quán)限執(zhí)行命令比如不必要的 sudo。不要直接執(zhí)行你不理解的命令。AI 可能會(huì)給出命令行建議但最終執(zhí)行權(quán)應(yīng)該在你手里。這也是我建議先在小測(cè)試目錄里跑通流程的原因。目錄越簡(jiǎn)單權(quán)限越清晰越不容易發(fā)生意外。把這套流程記成三步環(huán)境檢查、單任務(wù)驗(yàn)證、批量場(chǎng)景驗(yàn)證。多數(shù)啟動(dòng)問(wèn)題出在 Node 版本和終端權(quán)限多數(shù)批量問(wèn)題出在輸入格式、輸出命名和失敗重試多數(shù)質(zhì)量問(wèn)題出在需求沒有限定輸入輸出。先跑通最小路徑再逐步擴(kuò)大范圍會(huì)順手很多。