Claude Code 4.5 在 Windows 上安裝這件事我一開始以為就是npm install一條命令的事結(jié)果被 PowerShell 執(zhí)行策略、Node 版本、終端亂碼、路徑空格來回折騰了幾次才算徹底理順。這篇文章聚焦一件事把 Claude Code 4.5 從零裝到 Windows 上并且裝完能用、能登錄、能跑起來。不管你是第一次接觸命令行 AI 編程工具的老玩家還是剛在 Windows 上搭開發(fā)環(huán)境的新手這一期內(nèi)容都能讓你少走彎路。能裝完的人很多但裝完之后知道它為什么這樣跑、配置文件在哪、壞了怎么排查的人不多這恰恰是這篇想補(bǔ)上的部分。1. 裝之前先想明白Claude Code 4.5 在 Windows 上憑什么能跑1.1 它本質(zhì)是什么又依賴什么Claude Code 4.5 是 Anthropic 推出的命令行 AI 編程代理你把它理解為住在終端里的程序猿搭檔就行。你輸入自然語言指令它幫你讀代碼、改代碼、執(zhí)行命令、運(yùn)行測試甚至自己起終端跑腳本。它跟聊天網(wǎng)頁版最大的區(qū)別是它有本地環(huán)境的操作權(quán)限能直接觸碰你的項(xiàng)目文件。正因如此安裝它的前置條件跟普通 GUI 軟件完全不同。它不是下載一個.exe雙擊安裝而是通過 Node.js 的 npm 包管理器來安裝和運(yùn)行。也就是說Windows 上必須先有 Node.js 環(huán)境這是硬前提。很多人在安裝時報錯八成都是卡在這一步Node 版本太老、npm 不是最新、或者壓根沒裝 Node。理解了這一點(diǎn)后面的安裝邏輯就順了裝 Node → 用 npm 拉取 Claude Code 包 → 登錄認(rèn)證 → 初始化配置。整個過程跟你在服務(wù)器上裝一個命令行工具沒有本質(zhì)區(qū)別只是 Windows 在權(quán)限、路徑、編碼上有自己的脾氣。1.2 原生 Windows 和 WSL 兩條路線怎么選Claude Code 4.5 在 Windows 上實(shí)際有兩條運(yùn)行路線一條是直接在原生 Windows 環(huán)境里跑也就是你在 PowerShell 或 CMD 里直接執(zhí)行claude命令另一條是借助 Windows 自帶的 WSLLinux 子系統(tǒng)跑在 Ubuntu 等發(fā)行版里再通過 WSL 終端調(diào)用。這兩條路線我都在真實(shí)項(xiàng)目里試過差別非常明顯做個表方便你對照對比項(xiàng)原生 Windows 路線WSL 路線安裝難度低Node.js 裝完即可中需先啟用 WSL 并裝發(fā)行版命令兼容性依賴 Win32 命令部分 Unix 命令用不了完整的 Linux bash 生態(tài)文件訪問直接訪問C:\、D:\通過/mnt/c/訪問 Windows 文件跨盤有 IO 損耗穩(wěn)定性對中文路徑、空格路徑敏感相對穩(wěn)定但跨文件系統(tǒng)訪問慢適合場景日常項(xiàng)目在 Windows 上、不想折騰子系統(tǒng)項(xiàng)目本身在 Linux 服務(wù)器部署、重度依賴 Unix 工具鏈我的判斷是如果你只是想在 Windows 上體驗(yàn) Claude Code或者項(xiàng)目本身就托管在 Windows 環(huán)境里優(yōu)先走原生路線簡單直接。但如果你平時用 Docker、Linux 服務(wù)器部署或者項(xiàng)目代碼最終要跑到 Linux 上那 WSL 路線順手得多因?yàn)?Claude Code 在執(zhí)行命令時調(diào)用的都是系統(tǒng) shellLinux 的 bash 能處理的事情遠(yuǎn)多于 PowerShell。1.3 我對路線的最終建議我自己的主力環(huán)境是原生 Windows 偶爾切 WSL的組合。日常寫腳本、改項(xiàng)目用原生因?yàn)?Windows 的圖形化工具、GUI 編輯器配合起來方便需要跑 Linux 命令或者測試部署腳本時再切到 WSL 里啟動 Claude Code。這篇教程的主體部分以原生 Windows 為例因?yàn)閷Χ鄶?shù)讀者來說這是最容易復(fù)現(xiàn)的路徑。WSL 相關(guān)的內(nèi)容我會在安裝坑位章節(jié)里單獨(dú)補(bǔ)充尤其是子系統(tǒng)文件找不到和 Windows 與 Linux 文件共享這兩個高頻問題。不管哪條路線Claude Code 4.5 的安裝核心動作是一樣的先搞定 Node 環(huán)境再執(zhí)行 npm 安裝。2. 環(huán)境地基Node.js 裝不對后面全是白費(fèi)2.1 版本底線和 nvm-windows 管理Claude Code 4.5 官方要求 Node.js 版本有底線太老的版本比如 Node 14 及以下大概率裝不上或者裝上運(yùn)行時報錯。我實(shí)際驗(yàn)證下來Node.js 18 能跑但 Node 20 LTS 和 22 LTS 最省心。如果你機(jī)器上已經(jīng)有 Node先打開終端執(zhí)行node -v和npm -v看看版本一個低于 18一個低于 9都建議先升級再繼續(xù)。這里我強(qiáng)烈建議用 nvm-windows 來管理 Node 版本而不是直接去官網(wǎng)下載最新版安裝包。原因很實(shí)際Claude Code 只是你機(jī)器上無數(shù) npm 全局包之一今天是 Claude Code 4.5明天可能還有別的工具要求不同 Node 版本。nvm-windows 允許你在多個 Node 版本間自由切換想升就升想降就降避免為了裝一個工具把整個環(huán)境搞崩的尷尬局面。安裝 nvm-windows 的步驟不復(fù)雜去它的 GitHub Releases 頁面下載nvm-setup.exe按提示安裝。裝完打開終端執(zhí)行nvm version能輸出版本號就說明裝好了。然后執(zhí)行nvm install 20 nvm use 20這兩條命令分別完成 Node 20 的下載安裝、切換當(dāng)前使用的版本。切換后node -v應(yīng)該輸出v20.x.x之類的結(jié)果此時 Node 環(huán)境就緒了。提示nvm-windows 安裝完成后如果終端提示nvm 不是內(nèi)部或外部命令檢查一下環(huán)境變量 Path 里是否包含 nvm 的安裝目錄沒有的話手動加進(jìn)去再重開終端。2.2 PowerShell 執(zhí)行策略和終端選哪個Windows 上裝完 Node 之后還有個容易被忽略的坑PowerShell 的腳本執(zhí)行策略。npm 生成的.ps1命令文件默認(rèn)可能被 PowerShell 攔截執(zhí)行claude時直接報無法加載文件因?yàn)樵诖讼到y(tǒng)上禁止運(yùn)行腳本。這不是 Claude Code 的問題是 Windows 的安全機(jī)制。解決辦法是給當(dāng)前用戶開啟 RemoteSigned 執(zhí)行策略只對本人生效不會影響系統(tǒng)安全級別Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser執(zhí)行后輸入Y確認(rèn)即可。Windows Terminal 是我推薦的終端沒有之一——它對 UTF-8 的支持比傳統(tǒng) CMD 好得多Claude Code 輸出帶顏色和特殊字符時不會亂成一團(tuán)而且還支持多標(biāo)簽頁同時開一個 PowerShell 窗口和一個 WSL 窗口很方便。2.3 環(huán)境驗(yàn)證清單別急著裝 Claude Code先把環(huán)境驗(yàn)證一遍節(jié)省后面排查時間node -v npm -v where node where npmnode -v和npm -v確認(rèn)版本where node確認(rèn) Node 可執(zhí)行文件路徑。如果where node找不到路徑說明環(huán)境變量有問題npm 全局安裝的包對應(yīng)的命令也會找不到Claude Code 裝上了也啟動不了。還有一個細(xì)節(jié)npm 全局安裝目錄里的命令最終能不能直接在終端里執(zhí)行取決于 npm 全局 bin 目錄是否在系統(tǒng) PATH 里。可以用npm config get prefix查看全局目錄正常情況下 Windows 下是用戶目錄下的AppData\Roaming\npm這個目錄會自動加入 PATH基本不用手動處理。3. 核心安裝流程一條 npm 命令背后的細(xì)節(jié)3.1 全局安裝命令環(huán)境就緒后核心安裝動作就一條npm install -g anthropic-ai/claude-code-g表示全局安裝裝完以后的啟動命令claude可以在任意目錄的終端里直接調(diào)用。全局安裝的好處是你不需要在每個項(xiàng)目里都裝一遍也能讓 Claude Code 訪問到多個項(xiàng)目路徑。實(shí)際執(zhí)行時有一些體驗(yàn)上的優(yōu)化空間。如果你在的地區(qū)拉取 npm 官方源速度慢這個跟網(wǎng)絡(luò)環(huán)境有關(guān)表現(xiàn)是進(jìn)度條半天不動可以臨時切換到國內(nèi)鏡像源安裝速度快很多npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com如果不想每次都帶--registry參數(shù)可以通過npm config set registry永久切換但要注意鏡像源偶爾同步滯后Claude Code 剛發(fā)新版本時鏡像源可能還沒更新這時候安裝到的不是最新版。我的經(jīng)驗(yàn)是日常使用可以用鏡像遇到版本更新時臨時切回官方源裝一次。安裝過程正常會在幾秒到幾十秒內(nèi)完成輸出一堆依賴安裝日志最后出現(xiàn)類似added xxx packages in xxs的提示就算成功。如果你看到 WARN 級別的警告比如某個依賴版本有提示一般不影響使用不用緊張。3.2 驗(yàn)證安裝裝完先別急著用驗(yàn)證一下安裝結(jié)果claude --version能輸出 Claude Code 的版本號4.5 或?qū)?yīng)的實(shí)際版本號說明核心安裝沒問題。如果報claude 不是內(nèi)部或外部命令大概率是 npm 全局目錄沒進(jìn) PATH回到第二章的環(huán)境驗(yàn)證檢查一遍。下一步在任意一個項(xiàng)目目錄里執(zhí)行claude首次啟動會進(jìn)入交互界面一個帶輸入框的終端 UI。如果這一步能正常出現(xiàn) UI說明工具本身已經(jīng)跑起來了。這時先不急著操作看完第四章的登錄認(rèn)證再說。3.3 升級、降級、卸載的命令對照Claude Code 版本迭代很快升級和卸載是遲早要面對的事。常用命令我整理成表操作命令升級到最新版npm install -g anthropic-ai/claude-codelatest安裝指定版本npm install -g anthropic-ai/claude-code某個版本號卸載npm uninstall -g anthropic-ai/claude-code查看當(dāng)前版本claude --version查看可用的遠(yuǎn)端版本npm view anthropic-ai/claude-code versions有個比較隱蔽的坑claude命令有可能被系統(tǒng) PATH 中其他同名命令搶先命中。我在一臺機(jī)器上就遇到過執(zhí)行claude進(jìn)入了另一個完全不同的程序。排查方法是用where claude看命中的路徑到底指向哪里正常情況下應(yīng)該指向AppData\Roaming\npm\claude.cmd如果指向別處多半是 PATH 順序被改過調(diào)整 PATH 順序即可。4. 登錄認(rèn)證與配置讓 Claude Code 認(rèn)出你是誰4.1 兩種認(rèn)證方式安裝成功后Claude Code 還是一個沒有身份的工具你得告訴它你用的是哪個賬號、有沒有 API Key。目前主流的認(rèn)證方式有兩種。第一種是瀏覽器授權(quán)登錄。在 Claude Code 交互界面輸入/login或者直接執(zhí)行claude login工具會輸出一個鏈接用瀏覽器打開登錄 Claude 賬號并確認(rèn)授權(quán)授權(quán)完成回到終端Claude Code 就自動完成身份綁定。這種方式適合訂閱了 Claude 套餐的用戶。第二種是 API Key 方式。如果你是通過 Anthropic 的 API 平臺使用可以設(shè)置環(huán)境變量$env:ANTHROPIC_API_KEYsk-ant-你的密鑰設(shè)置之后 Claude Code 會優(yōu)先讀取這個環(huán)境變量作為憑證。但注意在 PowerShell 里設(shè)置的環(huán)境變量只在當(dāng)前窗口會話有效關(guān)掉終端就沒了。要永久生效可以通過 Windows 系統(tǒng)環(huán)境變量面板添加或者在 PowerShell 配置文件$PROFILE里寫入這一行。兩種方式我更推薦瀏覽器授權(quán)因?yàn)樗鼤詣犹幚?API 路由和憑證刷新不用手動維護(hù) Key。API Key 方式適合自動化場景或服務(wù)器環(huán)境比如配置到 CI/CD 管道里不想每次手動登錄。4.2 配置文件與自定義認(rèn)證完成后Claude Code 會在用戶目錄下創(chuàng)建配置文件目錄。在 Windows 原生環(huán)境下這個目錄在C:\Users\你的用戶名\.claude在 WSL 環(huán)境下則是~/.claude這個目錄里有幾個關(guān)鍵文件settings.json、credentials.json以及歷史記錄相關(guān)的文件。其中settings.json是你最常打交道的配置文件模型選擇、權(quán)限策略、自定義指令都寫在這里。我的一個簡單配置示例{ model: claude-sonnet-4-5, permissions: { allow: [ Bash(*) ], deny: [] }, maxTokens: 8192 }model指定默認(rèn)模型permissions控制 Claude Code 執(zhí)行本地命令時的權(quán)限allow列出允許執(zhí)行的操作deny列出禁止的操作。我一般會把Bash(*)放行讓它執(zhí)行終端命令更流暢但如果你對安全性要求高建議改成每次詢問授權(quán)避免它自動跑高風(fēng)險命令。注意配置文件是 JSON 格式改完記得檢查一下括號和逗號寫錯了會導(dǎo)致 Claude Code 啟動時讀配置失敗。改完配置后需要重啟claude進(jìn)程才會生效。4.3 首次啟動會遇到什么第一次登錄成功后啟動claude它會先做環(huán)境自檢然后顯示歡迎信息和使用說明。這中間可能會彈出一些權(quán)限詢問比如是否允許 Claude Code 讀取當(dāng)前目錄文件是否允許執(zhí)行 Bash 命令給出你的選擇即可。這里有一個容易被忽略的點(diǎn)Claude Code 在哪個目錄啟動默認(rèn)的工作范圍就是哪個目錄。大多數(shù)情況下你的項(xiàng)目代碼在哪個目錄就在哪個目錄啟動它這樣它讀文件和執(zhí)行命令的上下文才正確。不要從隨便一個系統(tǒng)目錄啟動否則它面對一堆無關(guān)文件會做大量無效工作。首次啟動還有一個推薦動作在交互界面輸入/help看一下當(dāng)前版本支持的命令列表。Claude Code 每次版本更新都可能增加新的斜杠命令比如/config打開配置、/clear清空對話上下文、/doctor做環(huán)境診斷。4.5 版本的/doctor我特別推薦它不是擺設(shè)執(zhí)行后會檢查依賴版本、配置合法性、認(rèn)證狀態(tài)能排查掉 80% 的安裝期問題。5. 安裝期高頻坑位我從裝崩幾次里總結(jié)的排查鏈路5.1 PowerShell 執(zhí)行策略報錯與權(quán)限問題這是新手最常遇到的第一道坎。癥狀是執(zhí)行claude后 PowerShell 報錯提示無法加載文件因?yàn)樵诖讼到y(tǒng)上禁止運(yùn)行腳本。原因前面講過就是腳本執(zhí)行策略默認(rèn)限制。解決方案是執(zhí)行策略改 RemoteSigned。但如果改完還報錯就別急著繼續(xù)。我的排查順序是先Get-ExecutionPolicy -List看當(dāng)前的策略作用域確認(rèn)是CurrentUser還是LocalMachine的限制再Get-Command claude看命令是否被識別還不行就手動執(zhí)行 npm 全局目錄下的claude.cmd文件看具體報什么錯誤。多數(shù)情況是執(zhí)行策略沒生效少數(shù)情況是環(huán)境變量 PATH 沒刷新重開終端再試即可。5.2 npm 下載緩慢、卡住、緩存損壞npm 執(zhí)行安裝時卡在進(jìn)度條不動最常見的兩種原因網(wǎng)絡(luò)源慢或者本地緩存壞了。網(wǎng)絡(luò)源的問題用前面說的鏡像源解決。緩存損壞的場景是安裝到一半強(qiáng)退再安裝時報各種integrity校驗(yàn)錯誤。我之前就遇到過 npm 緩存文件損壞導(dǎo)致的詭異報錯日志顯示校驗(yàn)失敗但重新裝還是一樣。當(dāng)時排查到最后發(fā)現(xiàn)是 npm 緩存目錄里有損壞的臨時文件。解決的辦法很簡單先清緩存再重裝npm cache clean --force npm install -g anthropic-ai/claude-code如果cache clean不行還有更徹底的方案手動刪除 npm 緩存目錄Windows 下一般位于C:\Users\你的用戶名\AppData\Local\npm-cache刪完重裝。注意刪除前確保沒有其他全局包正在安裝。5.3 中文用戶名與路徑空格Windows 如果用戶名是中文會導(dǎo)致 npm 全局目錄路徑、Claude Code 配置目錄路徑都含有非 ASCII 字符。大部分情況下能正常安裝但 Claude Code 在解析路徑、執(zhí)行某些 Linux 風(fēng)格命令時會對中文路徑處理異常。表現(xiàn)為啟動正常但一操作文件就報路徑錯誤。這種情況我沒有特別好的根治方案能提的建議有幾個一是盡量使用純英文的路徑比如把項(xiàng)目放到D:\projects而不是桌面二是如果跑在 WSL 里完全繞開中文路徑問題三是給 Windows 新建一個純英文用戶賬戶專門跑開發(fā)環(huán)境。說實(shí)話如果你預(yù)期要長期用這類命令行 AI 工具路徑這塊盡可能保持純英文是一個一勞永逸的選擇。路徑空格的坑也有點(diǎn)類似。Claude Code 的配置文件路徑、項(xiàng)目路徑如果帶空格部分命令拼接路徑時沒加引號就會斷成兩截。判斷依據(jù)是報錯信息里路徑被截?cái)嗷蛘哒也坏轿募?。特別是C:\Program Files這種系統(tǒng)目錄放項(xiàng)目倒是沒人會放那邊但有些工具裝到有空格的自定義目錄時需要留意。5.4 亂碼、WSL 子系統(tǒng)找不到等周邊坑Windows 終端顯示亂碼本質(zhì)上集中在編碼不匹配。Claude Code 輸出的是 UTF-8而傳統(tǒng) CMD 和某些老配置的 PowerShell 默認(rèn)按 GBK 解析于是中文、特殊字符全變成亂碼。我試過最有效的方案PowerShell 窗口標(biāo)題欄右鍵 → 屬性 → 字體選Consolas在 PowerShell 里執(zhí)行chcp 65001切換到 UTF-8直接換 Windows Terminal它默認(rèn) UTF-8亂碼問題少得多WSL 方向的坑我遇到最有代表性的是熱詞里常見的wsl -d ubuntu-22.04 系統(tǒng)找不到指定的文件。這個報錯 90% 是發(fā)行版名稱對不上。排查方式是執(zhí)行wsl -l -v看看當(dāng)前系統(tǒng)真實(shí)存在的發(fā)行版名稱然后按實(shí)際名字啟動。還有一種是 WSL2 發(fā)行版文件損壞需要wsl --shutdown重啟服務(wù)再試。Windows 與 Linux 共享文件也是一個繞不開的點(diǎn)。WSL 里能看到 Windows 的盤符路徑映射規(guī)則是C:\對應(yīng)/mnt/c/D 盤對應(yīng)/mnt/d/。你在 WSL 里跑 Claude Code 操作 Windows 目錄下的項(xiàng)目要讓 Claude Code 明確訪問的是/mnt/c/...路徑而不是默認(rèn)的 Linux 家目錄否則它會覺得當(dāng)前目錄什么都沒有?？缥募到y(tǒng)訪問確實(shí)比純 Linux 環(huán)境慢如果項(xiàng)目文件很大建議把代碼復(fù)制一份到 WSL 內(nèi)部目錄性能提升明顯。5.5 Docker Desktop 和 Claude Code 的配合熱詞里有人提到 Windows 安裝 Docker這也跟 Claude Code 扯得上關(guān)系。Claude Code 在部分場景會調(diào)用 Docker 來隔離執(zhí)行任務(wù)Docker Desktop 的 WSL2 后端和 Claude Code 之間需要配合。如果你在啟動 Claude Code 時遇到 Docker 相關(guān)的報錯先確認(rèn) Docker Desktop 狀態(tài)是 Running再看 WSL 里是否能正常執(zhí)行docker ps。Docker Desktop 裝好后默認(rèn)綁定的 WSL 發(fā)行版可能不是 Claude Code 所在的那一個需要在 Docker Desktop 的 Settings → Resources → WSL Integration 里把對應(yīng)發(fā)行版開關(guān)打開。這一條經(jīng)驗(yàn)我是實(shí)際踩過的。當(dāng)時在 WSL 里啟動 Claude Code它要啟動一個臨時容器做代碼沙箱結(jié)果死活連不上 Docker日志報權(quán)限和連接錯誤。排查到最后就是 WSL Integration 沒開啟。開啟之后關(guān)閉重開終端問題消失。寫在最后的一點(diǎn)實(shí)際操作體會Claude Code 4.5 在 Windows 上安裝說到底是環(huán)境正確性的驗(yàn)證過程。Node 版本對了PATH 對了權(quán)限策略對了剩下的npm install只是時間問題。我在實(shí)際折騰中最深的體會是不要一遇到報錯就重裝先讀報錯信息先確認(rèn)環(huán)境變量和執(zhí)行策略再看依賴緩存絕大多數(shù)安裝期問題都能在這幾步里解決。另外一個小技巧建議你保留安裝完順手執(zhí)行一次claude --version和claude /doctor把版本號和環(huán)境診斷結(jié)果記錄下來。等下次版本升級出問題對比一下當(dāng)時的輸出能省下大量排查時間。這一期說清楚了安裝下一期我準(zhǔn)備寫 Claude Code 4.5 在真實(shí)項(xiàng)目里怎么高效使用包括項(xiàng)目指令文件怎么寫、權(quán)限策略怎么配才能既安全又不礙事到時候見。