直接用yo code能跑通，但Node版本必须≥18.19.0（如18.19.0或20.18.0），选TypeScript模板更可靠，activationEvents建议设为["onCommand:extension.helloWorld"]，调试前需禁用非必要插件，并确保package.json中"main"指向正确编译路径。
直接用 yo code 就能跑通，但 Node 版本、生成器模板选型、调试入口配置这三处不调对，插件根本起不来。
node 版本必须 ≥18.19.0（不是 ≥18 就行）
很多教程写“Node ≥18 即可”，实际踩坑发现：18.0.0、18.18.0、23.0.0 都会卡在 yo code 后的交互环节，报错类似 Error: Cannot find module 'fs/promises' 或直接无响应。官方 generator-code 当前（2026 年 8 月）稳定兼容的是 18.19.0 和 20.18.0。Windows 用户尤其要注意——VSCode 自带的 Electron 内置 Node（如 v20.18.0）不影响插件开发环境，你本地终端的 node -v 才决定脚手架能否启动。
- 验证方式：
node -v输出必须是v18.19.0或v20.18.0 - 降级/升级推荐用
nvm-windows（Win）或nvm（macOS/Linux） - 别信
npm install -g n，它在 Windows 下常失效
选 TypeScript 模板比 JavaScript 更省事
虽然标题说“轻量级”，但用 JavaScript 模板反而容易掉坑：extension.js 里没有类型提示，改个 API 调用（比如 vscode.window.activeTextEditor）时，拼错属性名或漏判空值，调试窗口里只报 Cannot read property 'document' of undefined，得手动加一堆 if 判断。TypeScript 模板（src/extension.ts）自带严格检查，且 vscode 官方声明文件自动注入，vscode. 后按 Ctrl+Space 就能补全。
- 创建时选
New Extension (TypeScript)，别选 JavaScript - 如果已建 JS 项目，不建议中途改 TS——
tsconfig.json和构建脚本要重配，不如重跑yo code -
package.json中的activationEvents建议先设为["onCommand:extension.helloWorld"]，避免一打开编辑器就激活，拖慢启动
F5 调试失败？先关掉所有非必要插件
调试窗口打不开、命令搜不到 Hello World、右下角没弹窗——八成是其它插件干扰了激活流程。VSCode 的插件激活机制是事件驱动的，一旦某个插件在 activate 阶段抛未捕获异常，后续插件可能被跳过加载。
- 调试前，在主 VSCode 窗口按
Ctrl+Shift+P→ 输入Extensions: Show Enabled Extensions→ 禁用所有非系统插件（尤其是 GitLens、Prettier、ESLint 这类常驻型） - 调试窗口里按
Ctrl+Shift+U打开输出面板，切换到Log (Extension Host)，看有没有Activating extension 'xxx' failed类错误 - 别依赖 “Extension Developer Host” 标题栏识别调试窗口——它有时不刷新，认准窗口左下角是否显示
[Extension Development Host]
发布前必验：vsce 打包时的路径硬编码陷阱
用 vsce package 打出 .vsix 后，本地安装测试没问题，但别人装上就报 Cannot find module './out/extension'——大概率是 package.json 里 "main": "./out/extension.js" 没随构建结果更新。TypeScript 项目默认走 webpack 或 tsc 构建，但脚手架生成的 package.json 不会自动改 main 字段。
- 确认
src/extension.ts编译后是否真生成了out/extension.js（检查out/目录是否存在且非空） - 如果用了自定义构建（如
rollup），main必须指向最终 bundle 路径，比如"main": "./dist/extension.js" -
vsce package前务必先运行npm run compile（或npm run build），否则打包的是旧代码
真正卡住人的从来不是“怎么写功能”，而是 node 版本和构建路径这两个看似边缘的点——它们不出错时透明，一出错就全链路静默失败。
