企业官网建设流程全解析

1. 这个提示到底在说什么

你在 Windows 上装了 WSL，Ubuntu 里跑着项目，某天顺手在 WSL 目录里敲了cursor .，结果 Cursor 弹出一行黄字：Opening a WSL folder without the WSL extension is not recommended。翻译成人话就是：你现在打开的是一个 Linux 路径（比如\\wsl$\Ubuntu\home\you\project），但 Cursor 没装那个专门管远程连接的 WSL extension，所以它只能当普通文件夹看，终端、调试器、语言服务全都跑在 Windows 侧，路径映射、权限、换行符迟早出问题。

这个提示本身不致命，点掉也能用，但用久了你会遇到三类典型症状：终端里node、python找不到（因为用的是 Windows 的 PATH）；文件保存后权限变成 777 或干脆写不进去；调试器断点打不上。根因不是 Cursor 坏了，而是「打开方式」和「运行环境」错位了。

适合谁看：在 Windows 上用 Cursor 写 WSL 项目、被这行提示反复打扰、想一次性把远程连接配稳的人。下面我从 settings.json 骨架讲起，把 WSL extension 安装、远程连接、验证动作串成一条能照着做的流程。顺带说一句，如果你后面要接模型做代码补全或对话，TaoToken 的接入配置我也会放在同一份 settings 里，省得来回切文件。

2. 先把 WSL extension 和 settings.json 骨架立起来

Cursor 基于 VS Code 内核，所以它的扩展体系和 VS Code 高度一致。WSL extension 的正式名字是ms-vscode-remote.remote-wsl，它负责在 Windows 的 Cursor 和 WSL 里的一个轻量服务端之间搭桥。装它的方式有两种：图形界面点提示里的Install WSL Extension，或者命令行直接装。

命令行装更可控，打开 Cursor 的集成终端（注意是 Windows 侧的 PowerShell 或 CMD），执行：

cursor --install-extension ms-vscode-remote.remote-wsl

如果你习惯用 VS Code 的 CLI 语法，code --install-extension在 Cursor 里通常也能用，但保险起见用cursor前缀。装完可以用下面这条确认：

cursor --list-extensions | findstr remote-wsl

Windows 下findstr是原生可用的，Linux/macOS 换成grep。看到ms-vscode-remote.remote-wsl就说明装上了。

接下来是 settings.json。Cursor 的用户级配置在 Windows 上一般位于%APPDATA%\Cursor\User\settings.json，你也可以在 Cursor 里按Ctrl+Shift+P，输入Preferences: Open User Settings (JSON)直接打开。下面这份骨架是我实测下来比较稳的，重点在远程连接相关项和终端默认 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" }

逐项说一下为什么这么配。remote.WSL.fileWatcher.polling设为 true 是因为 WSL 的 inotify 在跨文件系统时经常漏事件，轮询虽然费一点 CPU，但能保证保存后热重载不抽风。remote.WSL.useShellEnvironment让远程会话继承 WSL 里的环境变量，这样你在.bashrc里配的 PATH、代理变量（如果有）能带进来。files.eol设成\n是防止 Windows 侧编辑器把换行符改成 CRLF，导致 Git diff 一片红。terminal.integrated.cwd用${workspaceFolder}保证终端一打开就在项目根目录，不用每次cd。

注意：remote.WSL.fileWatcher.polling在大项目里可能让 CPU 上去一点，如果你项目文件数超过几万，可以改成false并改用files.watcherExclude排除node_modules、.git这类目录。

如果你还要在 Cursor 里接模型做补全或对话，可以在同一份 settings.json 里加 TaoToken 的配置。TaoToken 是一个模型接入平台，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。配置片段如下，注意 API Key 建议放环境变量而不是硬编码：

{ "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"，这样远程会话也能读到。Key 的获取入口在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

3. 可复制的远程连接配置与打开流程

settings.json 只是静态配置，真正消除提示靠的是「用远程方式打开」。这里分两条路：一条是从 WSL 终端里发起，一条是从 Cursor 界面里发起。

从 WSL 终端发起最顺。在 Ubuntu 里cd到项目目录，然后：

cd ~/projects/my-app cursor .

如果 WSL extension 装好了，Cursor 会自动识别这是 WSL 路径，走远程连接，不再弹提示。如果还是弹，说明扩展没生效，重启一次 Cursor 再试。

从 Cursor 界面发起的话，按Ctrl+Shift+P打开命令面板，输入WSL: Connect to WSL using Distro in New Window，选中你的发行版（比如 Ubuntu-22.04），新窗口打开后再File > Open Folder选项目目录。这个流程对应你截图里的操作，但命令面板方式更稳，因为不依赖当前窗口状态。

远程连接建立后，左下角会显示WSL: Ubuntu-22.04这样的绿色标识。这时候你打开集成终端，uname -a应该返回 Linux 内核信息，而不是 Windows。这一步是判断「是否真的进了 WSL」的关键。

再补一个.vscode/settings.json（项目级）的配置，用来覆盖用户级里不适合项目的项：

{ "remote.WSL.fileWatcher.polling": false, "files.watcherExclude": { "**/node_modules/**": true, "**/.git/objects/**": true, "**/dist/**": true }, "python.defaultInterpreterPath": "/usr/bin/python3", "eslint.workingDirectories": ["."] }

项目级配置会覆盖用户级，所以大项目里把轮询关掉、用 watcherExclude 精准排除，比全局开轮询更合理。python.defaultInterpreterPath指向 WSL 里的解释器，避免 Cursor 误用 Windows 的 Python。

4. 验证请求与成功结果

配置改完不验证等于没配。我一般按下面四步走，每步都有明确的预期输出。

第一步，确认扩展已加载。在 Cursor 里按Ctrl+Shift+X打开扩展面板，搜索WSL，应该看到WSL扩展显示已安装且已启用。如果显示「需要重新加载」，点一下重载。

第二步，确认远程连接生效。新开一个 Cursor 窗口，用命令面板连 WSL，然后打开终端执行：

uname -a which node echo $PATH

预期是uname -a输出带Linux和microsoft-standard-WSL2字样；which node返回/home/you/.nvm/versions/node/...这类 Linux 路径，而不是/mnt/c/...；$PATH里应该包含/usr/local/sbin、/home/you/.local/bin这些 Linux 目录。

第三步，验证文件监听。在项目里改一个文件保存，看终端里跑着的 dev server 有没有热重载。如果没反应，回到 settings.json 把remote.WSL.fileWatcher.polling临时设为 true 再试，能热重载就说明是 inotify 的问题，保持轮询或加 watcherExclude。

第四步，验证模型接入（如果你配了 TaoToken）。在 Cursor 里发一条对话请求，或者用 curl 直接打 API：

curl -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 }'

预期返回一个 JSON，choices[0].message.content里有内容。如果返回 401，检查 Key 是否导出到了当前 shell；返回 404，检查 base URL 是不是https://taotoken.net/api而不是带/v1的变体。模型对话的入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，想直接试模型可以走这个。

四步都过，提示基本不会再出现，终端、调试、补全都在 WSL 侧跑，路径和权限问题也一并消失。

5. 本篇常见错排查

错误一：装了扩展还是弹提示。最常见的原因是 Cursor 没重启，扩展没加载。先Ctrl+Shift+P执行Developer: Reload Window。如果还不行，检查是不是装到了 VS Code 而不是 Cursor，两个编辑器的扩展目录是分开的，用cursor --list-extensions确认。

错误二：cursor .命令找不到。说明 Cursor 的 CLI 没加到 PATH。在 Cursor 里按Ctrl+Shift+P执行Shell Command: Install 'cursor' command，然后重开终端。WSL 里如果找不到，需要在 WSL 的.bashrc里把 Windows 侧的 Cursor 路径加进去，或者直接用命令面板方式打开。

错误三：终端里node版本和 WSL 里不一致。这是典型的「终端跑在 Windows 侧」。检查左下角有没有WSL: Ubuntu标识，没有就是没连上远程。另外terminal.integrated.defaultProfile.linux要设成bash或zsh，设成PowerShell会走 Windows 终端。

错误四：文件保存后权限变 777。这是从 Windows 侧写 WSL 文件导致的。确认你是通过远程连接打开的，而不是直接打开\\wsl$\...路径。files.eol设成\n也能减少换行符问题。

错误五：TaoToken 请求 401/404。401 是 Key 问题，确认TAOTOKEN_API_KEY在当前 shell 里echo得出来；404 是 base URL 问题，确认是https://taotoken.net/api。如果要在 WSL 里长期用，把 export 写进~/.bashrc并source一次。需要管理多个 Key 的话，控制台在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。

错误六：远程连接后扩展不生效。有些扩展需要装在 WSL 侧而不是 Windows 侧。在扩展面板里会显示「Install in WSL」按钮，点它。WSL extension 本身是装在 Windows 侧的，但语言服务器、linter 这类通常要装到 WSL 侧。

6. 把配置固化下来，下次直接进

整套流程走完，你会发现核心就三件事：装对扩展、用远程方式打开、settings.json 里把文件监听和终端 profile 配对。提示本身是个提醒，不是错误，但顺着它把远程连接配好，后面省的是调试器和权限的麻烦。

如果你经常在多个 WSL 发行版之间切，可以把常用发行版固定下来，命令面板里选一次之后 Cursor 会记住。长期做编码和 Agent 类任务的话，可以考虑 TaoToken 的 Coding Plan，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，配合远程连接用，模型请求和代码执行都在 WSL 侧闭环。Claude Code 相关的接入说明在 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite 。

最后留一个我自己的习惯：把用户级 settings.json 和项目级.vscode/settings.json分开维护，用户级放通用项（终端 profile、eol、遥测），项目级放项目相关项（watcherExclude、解释器路径）。这样换项目不用改全局，团队协作时项目级配置还能进 Git 共享。下次再看到那行黄字，直接按第 3 节的命令面板流程走一遍，两分钟就能进 WSL 环境。