VSCode代码片段插件本质是静态JSON配置：通过package.json的"contributes.snippets"声明语言ID对应的.snippets.json文件，无构建、无动态生成；需严格匹配语言ID、正确转义JSON中的和$、避免prefix冲突。
代码片段插件本质是 JSON + package.json 配置
VSCode 的「代码片段」插件不是运行时编译的程序，也不需要写 TypeScript 或激活逻辑——它只是把 snippets 目录下的 JSON 文件，通过 package.json 中的 "contributes.snippets" 字段声明给编辑器。用户触发 Ctrl+Space 或输入前缀时，VSCode 直接读取这些 JSON 并渲染补全项。
这意味着：没有构建步骤、不涉及 API 调用、无法动态生成片段。所有片段必须在插件安装时就静态定义好。
- 每个语言对应一个
.json片段文件（如javascript.json），文件名必须与 VSCode 内置语言 ID 一致（查语言 ID 可打开命令面板 →Developer: Inspect Editor Tokens and Scopes） -
package.json中必须包含"activationEvents": ["*"]或更精确的["onLanguage:python"]，否则插件不会加载片段 - 不要试图在
snippets里放 JS 文件或模板引擎——VSCode 只认 JSON 格式，且只解析"body"、"prefix"、"description"这几个字段
snippet JSON 的 body 字符串要转义反斜杠和美元符
写 "body": ["console.log('$1');"] 看似没问题，但实际插入后可能变成 console.log('undefined'); 或光标错位——因为 $1、$0、${2:default} 是 VSCode 的占位符语法，而 JSON 字符串本身要求反斜杠 必须双写，否则解析失败；同时 $ 在某些上下文（比如 shell 脚本片段）还容易被误解释。
- 所有
必须写成\，例如路径"src\utils\helper.ts"→ 正确；写成"srcutilshelper.ts"→ JSON 解析报错 - 要输出字面量
$，得写成$；想保留占位符就保持$1不变，但确保它在字符串内未被 JS 引擎提前处理（你不是在写 JS，是在写 JSON） - 多行 body 推荐用数组而非字符串：用
["function ${1:name}() {", " ${2:// body}", "}"]比拼接换行符更安全，VSCode 原生支持数组格式
调试片段不生效？先检查 language ID 和 scope
写了 typescript.json 却在 .ts 文件里看不到片段，大概率是 language ID 对不上。VSCode 的“TypeScript”语言 ID 是 typescript，但“TypeScript React”是 typescriptreact，“Vue SFC 中的 script setup” 是 vue（不是 vue-html）。片段只对声明的 language ID 生效，不继承、不 fallback。
- 打开一个目标文件 → 按
Ctrl+Shift+P→ 输入Change Language Mode→ 看右下角显示的 ID（如typescriptreact） - 在
package.json的contributes.snippets数组中，为不同语言分别声明，不能共用一个文件：{"language": "typescript", "path": "./snippets/typescript.json"}和{"language": "typescriptreact", "path": "./snippets/typescriptreact.json"} - 如果片段只应在特定作用域生效（如仅在
script标签内），目前 VSCode 不支持基于语法 scope 的条件加载，只能靠语言 ID 区分
发布前务必验证 snippet prefix 是否有冲突
VSCode 不阻止你定义 "prefix": "log"，但它会和内置的 console.log 片段、其他已安装插件的 log 片段竞争。用户输入 log + Tab 时，VSCode 按插件安装顺序或匹配精度决定展示哪个——没有优先级配置项。
- 用冷门但语义清晰的 prefix，比如
mylog、dbg，而不是覆盖通用词如if、for - 本地测试时，禁用其他代码片段插件（尤其是
JavaScript (ES6) code snippets这类流行插件），避免干扰判断 - 发布后若用户反馈“没出现”，第一反应不是代码错，而是检查是否被别的插件屏蔽了——可以让他们在命令面板执行
Insert Snippet手动选择你的片段，绕过前缀匹配
真正麻烦的从来不是写 JSON，而是让片段在正确的时间、正确的文件、以正确的形态出现在用户眼前。语言 ID 错一位、prefix 太泛、JSON 转义漏一个反斜杠，都会导致它静默失效，且没有任何错误提示。
