1. 這個(gè)提示到底在說(shuō)什么你在 Windows 上裝了 WSLUbuntu 里跑著項(xiàng)目某天順手在 WSL 目錄里敲了cursor .結(jié)果 Cursor 彈出一行黃字Opening a WSL folder without the WSL extension is not recommended。翻譯成人話(huà)就是你現(xiàn)在打開(kāi)的是一個(gè) Linux 路徑比如\\wsl$\Ubuntu\home\you\project但 Cursor 沒(méi)裝那個(gè)專(zhuān)門(mén)管遠(yuǎn)程連接的 WSL extension所以它只能當(dāng)普通文件夾看終端、調(diào)試器、語(yǔ)言服務(wù)全都跑在 Windows 側(cè)路徑映射、權(quán)限、換行符遲早出問(wèn)題。這個(gè)提示本身不致命點(diǎn)掉也能用但用久了你會(huì)遇到三類(lèi)典型癥狀終端里node、python找不到因?yàn)橛玫氖?Windows 的 PATH文件保存后權(quán)限變成 777 或干脆寫(xiě)不進(jìn)去調(diào)試器斷點(diǎn)打不上。根因不是 Cursor 壞了而是「打開(kāi)方式」和「運(yùn)行環(huán)境」錯(cuò)位了。適合誰(shuí)看在 Windows 上用 Cursor 寫(xiě) WSL 項(xiàng)目、被這行提示反復(fù)打擾、想一次性把遠(yuǎn)程連接配穩(wěn)的人。下面我從 settings.json 骨架講起把 WSL extension 安裝、遠(yuǎn)程連接、驗(yàn)證動(dòng)作串成一條能照著做的流程。順帶說(shuō)一句如果你后面要接模型做代碼補(bǔ)全或?qū)υ?huà)TaoToken 的接入配置我也會(huì)放在同一份 settings 里省得來(lái)回切文件。2. 先把 WSL extension 和 settings.json 骨架立起來(lái)Cursor 基于 VS Code 內(nèi)核所以它的擴(kuò)展體系和 VS Code 高度一致。WSL extension 的正式名字是ms-vscode-remote.remote-wsl它負(fù)責(zé)在 Windows 的 Cursor 和 WSL 里的一個(gè)輕量服務(wù)端之間搭橋。裝它的方式有兩種圖形界面點(diǎn)提示里的Install WSL Extension或者命令行直接裝。命令行裝更可控打開(kāi) Cursor 的集成終端注意是 Windows 側(cè)的 PowerShell 或 CMD執(zhí)行cursor --install-extension ms-vscode-remote.remote-wsl如果你習(xí)慣用 VS Code 的 CLI 語(yǔ)法code --install-extension在 Cursor 里通常也能用但保險(xiǎn)起見(jiàn)用cursor前綴。裝完可以用下面這條確認(rèn)cursor --list-extensions | findstr remote-wslWindows 下findstr是原生可用的Linux/macOS 換成grep?？吹絤s-vscode-remote.remote-wsl就說(shuō)明裝上了。接下來(lái)是 settings.json。Cursor 的用戶(hù)級(jí)配置在 Windows 上一般位于%APPDATA%\Cursor\User\settings.json你也可以在 Cursor 里按CtrlShiftP輸入Preferences: Open User Settings (JSON)直接打開(kāi)。下面這份骨架是我實(shí)測(cè)下來(lái)比較穩(wěn)的重點(diǎn)在遠(yuǎn)程連接相關(guān)項(xiàng)和終端默認(rèn) profile{ remote.WSL.fileWatcher.polling: true, remote.WSL.useShellEnvironment: true, remote.autoForwardPorts: true, remote.restoreForwardedPorts: true, terminal.integrated.defaultProfile.linux: bash, terminal.integrated.defaultProfile.windows: PowerShell, terminal.integrated.cwd: ${workspaceFolder}, files.eol: \n, editor.formatOnSave: true, telemetry.telemetryLevel: off }逐項(xiàng)說(shuō)一下為什么這么配。remote.WSL.fileWatcher.polling設(shè)為 true 是因?yàn)?WSL 的 inotify 在跨文件系統(tǒng)時(shí)經(jīng)常漏事件輪詢(xún)雖然費(fèi)一點(diǎn) CPU但能保證保存后熱重載不抽風(fēng)。remote.WSL.useShellEnvironment讓遠(yuǎn)程會(huì)話(huà)繼承 WSL 里的環(huán)境變量這樣你在.bashrc里配的 PATH、代理變量如果有能帶進(jìn)來(lái)。files.eol設(shè)成\n是防止 Windows 側(cè)編輯器把換行符改成 CRLF導(dǎo)致 Git diff 一片紅。terminal.integrated.cwd用${workspaceFolder}保證終端一打開(kāi)就在項(xiàng)目根目錄不用每次cd。注意remote.WSL.fileWatcher.polling在大項(xiàng)目里可能讓 CPU 上去一點(diǎn)如果你項(xiàng)目文件數(shù)超過(guò)幾萬(wàn)可以改成false并改用files.watcherExclude排除node_modules、.git這類(lèi)目錄。如果你還要在 Cursor 里接模型做補(bǔ)全或?qū)υ?huà)可以在同一份 settings.json 里加 TaoToken 的配置。TaoToken 是一個(gè)模型接入平臺(tái)官網(wǎng)在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端點(diǎn)是 https://taotoken.net/api 。配置片段如下注意 API Key 建議放環(huán)境變量而不是硬編碼{ taotoken.apiBase: https://taotoken.net/api, taotoken.apiKey: ${env:TAOTOKEN_API_KEY}, taotoken.defaultModel: claude-sonnet-4-20250514 }然后在 WSL 的~/.bashrc里加一行export TAOTOKEN_API_KEY你的key這樣遠(yuǎn)程會(huì)話(huà)也能讀到。Key 的獲取入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。3. 可復(fù)制的遠(yuǎn)程連接配置與打開(kāi)流程settings.json 只是靜態(tài)配置真正消除提示靠的是「用遠(yuǎn)程方式打開(kāi)」。這里分兩條路一條是從 WSL 終端里發(fā)起一條是從 Cursor 界面里發(fā)起。從 WSL 終端發(fā)起最順。在 Ubuntu 里cd到項(xiàng)目目錄然后cd ~/projects/my-app cursor .如果 WSL extension 裝好了Cursor 會(huì)自動(dòng)識(shí)別這是 WSL 路徑走遠(yuǎn)程連接不再?gòu)椞崾?。如果還是彈說(shuō)明擴(kuò)展沒(méi)生效重啟一次 Cursor 再試。從 Cursor 界面發(fā)起的話(huà)按CtrlShiftP打開(kāi)命令面板輸入WSL: Connect to WSL using Distro in New Window選中你的發(fā)行版比如 Ubuntu-22.04新窗口打開(kāi)后再File Open Folder選項(xiàng)目目錄。這個(gè)流程對(duì)應(yīng)你截圖里的操作但命令面板方式更穩(wěn)因?yàn)椴灰蕾?lài)當(dāng)前窗口狀態(tài)。遠(yuǎn)程連接建立后左下角會(huì)顯示W(wǎng)SL: Ubuntu-22.04這樣的綠色標(biāo)識(shí)。這時(shí)候你打開(kāi)集成終端uname -a應(yīng)該返回 Linux 內(nèi)核信息而不是 Windows。這一步是判斷「是否真的進(jìn)了 WSL」的關(guān)鍵。再補(bǔ)一個(gè).vscode/settings.json項(xiàng)目級(jí)的配置用來(lái)覆蓋用戶(hù)級(jí)里不適合項(xiàng)目的項(xiàng){ remote.WSL.fileWatcher.polling: false, files.watcherExclude: { **/node_modules/**: true, **/.git/objects/**: true, **/dist/**: true }, python.defaultInterpreterPath: /usr/bin/python3, eslint.workingDirectories: [.] }項(xiàng)目級(jí)配置會(huì)覆蓋用戶(hù)級(jí)所以大項(xiàng)目里把輪詢(xún)關(guān)掉、用 watcherExclude 精準(zhǔn)排除比全局開(kāi)輪詢(xún)更合理。python.defaultInterpreterPath指向 WSL 里的解釋器避免 Cursor 誤用 Windows 的 Python。4. 驗(yàn)證請(qǐng)求與成功結(jié)果配置改完不驗(yàn)證等于沒(méi)配。我一般按下面四步走每步都有明確的預(yù)期輸出。第一步確認(rèn)擴(kuò)展已加載。在 Cursor 里按CtrlShiftX打開(kāi)擴(kuò)展面板搜索WSL應(yīng)該看到WSL擴(kuò)展顯示已安裝且已啟用。如果顯示「需要重新加載」點(diǎn)一下重載。第二步確認(rèn)遠(yuǎn)程連接生效。新開(kāi)一個(gè) Cursor 窗口用命令面板連 WSL然后打開(kāi)終端執(zhí)行uname -a which node echo $PATH預(yù)期是uname -a輸出帶Linux和microsoft-standard-WSL2字樣which node返回/home/you/.nvm/versions/node/...這類(lèi) Linux 路徑而不是/mnt/c/...$PATH里應(yīng)該包含/usr/local/sbin、/home/you/.local/bin這些 Linux 目錄。第三步驗(yàn)證文件監(jiān)聽(tīng)。在項(xiàng)目里改一個(gè)文件保存看終端里跑著的 dev server 有沒(méi)有熱重載。如果沒(méi)反應(yīng)回到 settings.json 把remote.WSL.fileWatcher.polling臨時(shí)設(shè)為 true 再試能熱重載就說(shuō)明是 inotify 的問(wèn)題保持輪詢(xún)或加 watcherExclude。第四步驗(yàn)證模型接入如果你配了 TaoToken。在 Cursor 里發(fā)一條對(duì)話(huà)請(qǐng)求或者用 curl 直接打 APIcurl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 16 }預(yù)期返回一個(gè) JSONchoices[0].message.content里有內(nèi)容。如果返回 401檢查 Key 是否導(dǎo)出到了當(dāng)前 shell返回 404檢查 base URL 是不是https://taotoken.net/api而不是帶/v1的變體。模型對(duì)話(huà)的入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 想直接試模型可以走這個(gè)。四步都過(guò)提示基本不會(huì)再出現(xiàn)終端、調(diào)試、補(bǔ)全都在 WSL 側(cè)跑路徑和權(quán)限問(wèn)題也一并消失。5. 本篇常見(jiàn)錯(cuò)排查錯(cuò)誤一裝了擴(kuò)展還是彈提示。最常見(jiàn)的原因是 Cursor 沒(méi)重啟擴(kuò)展沒(méi)加載。先CtrlShiftP執(zhí)行Developer: Reload Window。如果還不行檢查是不是裝到了 VS Code 而不是 Cursor兩個(gè)編輯器的擴(kuò)展目錄是分開(kāi)的用cursor --list-extensions確認(rèn)。錯(cuò)誤二cursor .命令找不到。說(shuō)明 Cursor 的 CLI 沒(méi)加到 PATH。在 Cursor 里按CtrlShiftP執(zhí)行Shell Command: Install cursor command然后重開(kāi)終端。WSL 里如果找不到需要在 WSL 的.bashrc里把 Windows 側(cè)的 Cursor 路徑加進(jìn)去或者直接用命令面板方式打開(kāi)。錯(cuò)誤三終端里node版本和 WSL 里不一致。這是典型的「終端跑在 Windows 側(cè)」。檢查左下角有沒(méi)有WSL: Ubuntu標(biāo)識(shí)沒(méi)有就是沒(méi)連上遠(yuǎn)程。另外terminal.integrated.defaultProfile.linux要設(shè)成bash或zsh設(shè)成PowerShell會(huì)走 Windows 終端。錯(cuò)誤四文件保存后權(quán)限變 777。這是從 Windows 側(cè)寫(xiě) WSL 文件導(dǎo)致的。確認(rèn)你是通過(guò)遠(yuǎn)程連接打開(kāi)的而不是直接打開(kāi)\\wsl$\...路徑。files.eol設(shè)成\n也能減少換行符問(wèn)題。錯(cuò)誤五TaoToken 請(qǐng)求 401/404。401 是 Key 問(wèn)題確認(rèn)TAOTOKEN_API_KEY在當(dāng)前 shell 里echo得出來(lái)404 是 base URL 問(wèn)題確認(rèn)是https://taotoken.net/api。如果要在 WSL 里長(zhǎng)期用把 export 寫(xiě)進(jìn)~/.bashrc并source一次。需要管理多個(gè) Key 的話(huà)控制臺(tái)在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。錯(cuò)誤六遠(yuǎn)程連接后擴(kuò)展不生效。有些擴(kuò)展需要裝在 WSL 側(cè)而不是 Windows 側(cè)。在擴(kuò)展面板里會(huì)顯示「Install in WSL」按鈕點(diǎn)它。WSL extension 本身是裝在 Windows 側(cè)的但語(yǔ)言服務(wù)器、linter 這類(lèi)通常要裝到 WSL 側(cè)。6. 把配置固化下來(lái)下次直接進(jìn)整套流程走完你會(huì)發(fā)現(xiàn)核心就三件事裝對(duì)擴(kuò)展、用遠(yuǎn)程方式打開(kāi)、settings.json 里把文件監(jiān)聽(tīng)和終端 profile 配對(duì)。提示本身是個(gè)提醒不是錯(cuò)誤但順著它把遠(yuǎn)程連接配好后面省的是調(diào)試器和權(quán)限的麻煩。如果你經(jīng)常在多個(gè) WSL 發(fā)行版之間切可以把常用發(fā)行版固定下來(lái)命令面板里選一次之后 Cursor 會(huì)記住。長(zhǎng)期做編碼和 Agent 類(lèi)任務(wù)的話(huà)可以考慮 TaoToken 的 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 配合遠(yuǎn)程連接用模型請(qǐng)求和代碼執(zhí)行都在 WSL 側(cè)閉環(huán)。Claude Code 相關(guān)的接入說(shuō)明在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 。最后留一個(gè)我自己的習(xí)慣把用戶(hù)級(jí) settings.json 和項(xiàng)目級(jí).vscode/settings.json分開(kāi)維護(hù)用戶(hù)級(jí)放通用項(xiàng)終端 profile、eol、遙測(cè)項(xiàng)目級(jí)放項(xiàng)目相關(guān)項(xiàng)watcherExclude、解釋器路徑。這樣換項(xiàng)目不用改全局團(tuán)隊(duì)協(xié)作時(shí)項(xiàng)目級(jí)配置還能進(jìn) Git 共享。下次再看到那行黃字直接按第 3 節(jié)的命令面板流程走一遍兩分鐘就能進(jìn) WSL 環(huán)境。