调试VSCode插件时，program字段不能指向TS/JS源码，必须通过extensionHost类型配置，用--install-extension参数加载已打包的.vsix文件，并配合preLaunchTask确保打包完成。
调试插件时 launch.json 的 program 字段必须指向 .vsix 文件
VSCode 插件本身是用 TypeScript 编写的，但调试运行时不是直接跑源码，而是加载打包后的 .vsix 包。如果你在 launch.json 里把 "program" 指向 extension.ts 或 out/extension.js，启动调试会失败并报错 Cannot find module 'vscode' 或 Extension host terminated unexpectedly。
正确做法是：确保插件已打包（vsce package），然后在调试配置中指定该 .vsix 路径：
{
"version": "0.2.0",
"configurations": [
{
"name": "Launch Extension",
"type": "extensionHost",
"request": "launch",
"runtimeExecutable": "${execPath}",
"args": [
"--extensionDevelopmentPath=${workspaceFolder}",
"--extensionTestsPath=${workspaceFolder}/out/test",
"--install-extension=${workspaceFolder}/my-extension-1.0.0.vsix"
],
"outFiles": ["${workspaceFolder}/out/**/*.js"],
"preLaunchTask": "package"
}
]
}
-
--install-extension参数必须是绝对路径或相对于${workspaceFolder}的有效.vsix文件 - 如果没生成
.vsix，调试前务必加"preLaunchTask": "package"并在tasks.json中定义打包任务 - Windows 下路径含空格时，
--install-extension值需用双引号包裹（VSCode 1.89+ 已修复部分场景，但保守起见仍建议加引号）
CI 环境下无法调用 VSCode UI，改用 headless 模式运行测试
GitHub Actions、GitLab CI 等持续集成环境默认无图形界面，直接运行 code --extensionDevelopment 会卡住或报错 Failed to get display。你不能依赖“弹出新窗口”这种交互式调试方式。
必须切换到 headless 测试模式，使用 vscode-test 提供的 CLI 工具：
- 安装依赖：
npm install --save-dev @vscode/test-electron - 测试脚本示例（
test/runTest.js）中调用runTests()，传入extensionDevelopmentPath和extensionTestsPath - CI 中执行命令：
npx @vscode/test-electron --extensionDevelopmentPath=. --extensionTestsPath=./out/test - 注意：Electron 版本需与目标 VSCode 兼容（例如 VSCode 1.89 对应 Electron 25，不匹配会导致
ERR_CONNECTION_REFUSED）
调试器连不上 extensionHost，检查 webSocket 端口和 --disable-extensions 冲突
本地调试插件时，常见现象是断点不命中、调试控制台空白、F5 启动后立即退出。多数情况是调试通道被阻断：
- VSCode 默认为插件调试分配一个随机 WebSocket 端口（如
ws://localhost:6060/...），若系统防火墙或公司代理拦截了该端口，调试器无法 attach - 某些企业策略会强制注入
--disable-extensions启动参数，导致你的插件根本没加载——检查进程命令行：ps aux | grep code（macOS/Linux）或任务管理器详情页（Windows） - 调试器类型必须是
extensionHost，不是node或chrome；类型写错会导致 VSCode 尝试用错误协议连接 - 如果使用 WSL2，
localhost在 Windows 和 Linux 子系统中指向不同网络栈，需显式设"port": 9333并确认端口转发已开
CI 中 test runner 找不到 mocha 或找不到 test 文件，根源在 out 目录结构
插件测试通常基于 Mocha，但 CI 报错 Error: Cannot find module 'mocha' 或 No test files found 很少是依赖没装，更多是构建产物路径错位：
-
vscode-test只认out/test/index.js（或out/test/suite/index.js）作为入口，不是src/test/下的 TS 文件 - 确保
tsconfig.json的"outDir"设为"out"，且"rootDir"指向"src"；否则编译后文件散落在各处，测试 runner 扫不到 - CI 中若用
npm ci，需确认devDependencies包含mocha、chai、@types/mocha，且版本与vscode-test兼容（例如 v2.4+ 要求 mocha ≥10） - 不要在
package.json的"scripts"里写"test": "mocha out/test"—— 这绕过了vscode-test的沙箱环境，测的不是真实插件行为
最易被忽略的是：CI 构建阶段是否真的执行了 tsc 编译？很多 pipeline 忘记加 npm run compile 或 npm run build 步骤，导致 out/ 目录为空，测试自然失败。
