必须先确认插件是否被VSCode加载：打开主窗口DevTools Console，刷新后查看是否有“Activating extension failed”或“Cannot find module”报错；若无报错但图标灰色，检查package.json中main路径是否正确指向已编译的JS文件（如./out/extension.js），并确保activationEvents声明匹配触发条件。
调试 VSCode 插件时，activate() 没执行、console.log 不见、断点不命中——八成不是代码写错了，而是模块根本没加载成功。关键得先确认：VSCode 真的把你的插件代码读进来了吗？
如何确认插件模块是否被加载
VSCode 加载插件分两步：先读取 package.json 声明，再按 main 字段路径动态 require() 入口文件。任一环节失败，插件就静默消失。
- 打开命令面板（
Ctrl+Shift+P），运行Developer: Toggle Developer Tools，切换到 Console 标签页 - 在主 VSCode 窗口（非开发主机窗口）中刷新页面（
Ctrl+R），观察是否有类似Activating extension 'ms-python.python' failed或Cannot find module './extension'的报错 - 若无报错但插件图标仍灰色，检查
package.json中的main路径是否拼写错误，比如写成"main": "./src/extension.js"却实际生成了./out/extension.js - Windows 用户注意反斜杠：
"main": ".\out\extension.js"在某些旧版 Node.js 下会解析失败，统一用正斜杠"main": "./out/extension.js"
为什么 require('./xxx.js') 报错 “Cannot find module”
这不是路径不存在，而是 VSCode 的模块解析规则和你预期不同：它不走 node_modules，也不支持 exports 字段，只认 main + 相对路径 + 同步 require()。
-
main必须指向一个真实存在的 JS 文件（不能是 TS 源码，也不能是未编译的.ts） - 如果用了构建工具（如 webpack），确保输出目录（如
./out）已生成，且package.json的main指向该产物，而非源码 - 避免在
main文件顶部使用动态import()或条件require()—— VSCode 加载器只执行顶层同步逻辑，异步导入会跳过激活流程 - 别依赖
__dirname拼路径：插件包解压后结构可能扁平化，__dirname指向的是~/.vscode/extensions/author.name-1.0.0/，不是项目根目录
ABI 不匹配导致 .node 原生模块加载失败
如果你的插件 require('./binding.node') 直接报 Cannot find module，且确认路径无误，大概率是 ABI 版本冲突。VSCode 1.90+ 内置 Node.js 22.4.0（napi_build_version=9），而大多数预编译的 .node 文件仍是 napi=8。
- 在开发者工具 Console 中执行
process.versions.napi，输出"9"就坐实了 ABI 问题 - 不要用系统
npm rebuild，那只会用你本地 Node.js（比如 v20.x）重编，还是napi=8 - 必须调用 VSCode 自带的 Node.js 运行时：macOS 示例为
~/Applications/Visual Studio Code.app/Contents/Frameworks/Code Helper (Renderer).app/Contents/MacOS/Code Helper (Renderer) --type=extensionHost node /usr/bin/npm rebuild --napi-build-version=9 --runtime=electron --target=34.0.0 - 重编译后删掉
node_modules/.pnpm和out/，防止旧缓存干扰
插件加载失败却没有任何错误提示
最棘手的情况：插件列表里显示“已安装”，图标灰色，控制台空空如也，连 Activating extension 都没打印。这往往是因为 activationEvents 声明太窄，或者 package.json 缺少必要字段。
- 检查
package.json是否包含"activationEvents"字段；若为空数组或缺失，插件默认只在onStartup时加载，但 VSCode 可能因性能策略延迟甚至跳过 - 确保有
"main"、"version"、"engines"（尤其是"vscode": "^1.85.0"）三个必填字段，缺一则整个插件被忽略 - 禁用所有其他插件，用
code --disable-extensions --user-data-dir=/tmp/vscode-test启动干净环境测试，排除冲突干扰 - 手动触发：新建一个
test.py文件（若插件声明了onLanguage:python），保存后看图标是否变亮——这是验证 activationEvents 是否生效的最快方式
模块加载排错的核心在于：VSCode 不报错 ≠ 模块已加载。它会安静地跳过任何不符合规范的插件声明，连日志都懒得写。盯住主窗口的 DevTools Console，而不是开发主机窗口，才是第一道关卡。
