vscode插件开发必须使用纯英文路径，因windows下node.js（cp936）与vs code调试协议（utf-8）路径编码不匹配，会导致调试失败、模块找不到、launch.json加载异常、.vsix打包损坏及用户端资源加载失败。
VSCode插件开发时，项目路径含中文会直接导致调试失败
插件开发不是普通编辑，vscode-extension-dev 启动的调试器（Extension Development Host）会调用 Node.js 的 child_process.spawn 加载你的插件入口、运行测试套件、甚至启动语言服务器。Windows 下若项目路径含中文（如 D:我的插件my-ext），Node.js 默认用 CP936 解析路径，而 VS Code 调试协议传的是 UTF-8 字节流——两者不匹配，结果就是：Error: spawn EACCES、Cannot find module 'D:我的插件my-extoutextension.js' 或直接卡在「Starting extension host...」不动。
这不是插件代码写错了，是底层路径解析崩了。你改 package.json 的 main 字段、加 require.resolve 包裹、甚至手动 decodeURIComponent 都没用——问题出在进程启动那一瞬间。
- 必须把整个插件项目移到纯英文路径下，例如
C:devmy-ext或D:projects scode-myext - 不要尝试用
chcp 65001临时切代码页：VS Code 调试器启动时不会继承终端的 code page 设置 - 别指望
vsce package能绕过——打包阶段同样会读取package.json中的路径字段，中文路径会导致生成的.vsix内部资源引用损坏
调试 launch.json 里 path 字段不能写中文，连注释都不行
VS Code 插件调试靠 .vscode/launch.json 控制启动行为，其中 runtimeExecutable、args、env 里任何涉及路径的值，只要含中文字符，就会被 cppvsdbg 或 node 子进程拒绝解析。更隐蔽的是：哪怕你只在注释里写了中文路径（比如 // 测试路径：D:插件源码），某些旧版 VS Code（2025.12 前）的 JSON 解析器会因 BOM 或编码识别错误，导致整个 launch.json 加载失败，调试按钮灰掉。
-
runtimeExecutable必须指向英文路径下的Code.exe，例如"C:\tools\vscode\Code.exe"，而非"D:\开发工具\VSCode\Code.exe" -
args数组中所有字符串（尤其是--extensionDevelopmentPath参数）必须是 UTF-8 编码且不含中文，推荐用path.join(__dirname, '..')动态生成再复制粘贴进 JSON - 删掉所有中文注释；保存前确认文件编码为 UTF-8 无 BOM（VS Code 状态栏右下角点编码 → 选 “Save with Encoding” → “UTF-8”）
插件代码里 require() 和 __dirname 无法安全处理中文路径
你在插件主文件（src/extension.ts）里写 require('./config.json') 或 path.join(__dirname, 'assets', 'icon.png')，看似没问题，但一旦用户把插件安装到中文路径的 VS Code 扩展目录（比如 C:Users张三.vscodeextensionsmy-ext），Node.js 的 fs.readFileSync 就可能返回乱码或抛 ENOENT——因为模块加载器对路径的 normalize 和 resolve 在 Windows 上不稳定。
- 避免硬编码相对路径，改用
vscode.ExtensionContext.extensionUri构建 URI：vscode.Uri.joinPath(context.extensionUri, 'assets', 'icon.png') - 读取配置文件时，优先用
vscode.workspace.getConfiguration()，而不是fs.readFileSync(path) - 如果真要读本地文件，用
vscode.workspace.fs.readFile(uri)（返回Uint8Array），它绕过 Node.js 的 fs 层，由 VS Code 主进程处理路径
发布前检查 .vsix 包内路径是否干净
vsce package 打包时会把 package.json、out/、icons/ 全部塞进 ZIP，但若你本地路径含中文，某些版本的 vsce（v2.14.0 之前）会把中文文件名用错误编码写入 ZIP 目录结构，导致用户安装后图标不显示、语言包加载失败、甚至插件禁用。
- 打包前执行
vsce ls查看即将打包的文件列表，确认没有???.png或乱码路径 - 用 7-Zip 手动打开生成的
.vsix（本质是 ZIP），检查根目录和out/下所有路径是否全英文、无空格 - CI 流水线里强制设置工作目录为
/tmp/vscode-ext（Linux）或C: scode-ext（Windows），杜绝本地路径污染
中文路径不是“看起来能跑”，而是会在调试、打包、用户安装三个环节分别崩一次。从创建项目第一天起就用英文命名，比事后查日志强十倍。
