VS Code 用户代码片段按文件名模式限定展开范围

同一个 VS Code 用户代码片段如果在所有脚本、测试文件甚至生成目录里都出现，问题通常不在片段 body，而在适用范围没有收窄。稳定的做法是：先用语言专用文件或 scope 限定语言，再用 include 指定文件名或路径模式，最后用 exclude 排除不应出现的目录与文件。exclude 与 include 同时命中时，以排除规则为准。

官方地址：https://code.visualstudio.com/docs/editing/userdefinedsnippets

先确定片段文件和语言边界

在命令面板执行“Preferences: Configure User Snippets”，如果片段只服务一种语言，可以直接选择语言专用文件，例如 shellscript.json。这种方式适合只在 Shell 文件中使用的片段。需要跨语言复用时，再新建全局 .code-snippets 文件，并用逗号分隔的语言标识写入 scope。

这里要区分“语言范围”和“文件范围”：scope 判断当前编辑器的语言模式，include、exclude 进一步判断当前文件名或相对路径。空文件可能暂时被识别成 Plain Text，因此先在状态栏确认语言模式，再排查 glob。

用 include 和 exclude 收窄文件名模式

下面的示例让一个 Shell 片段只在脚本文件中出现，同时避开 vendor 和生成文件目录。它使用全局片段文件的 JSONC 写法，注释只用于解释字段，保存后仍由 VS Code 的片段编辑器解析。

{
  // 片段名称会出现在 Insert Snippet 列表中
  "Shell safe header": {
    // 输入 shh 时显示这个片段
    "prefix": "shh",
    // 先限制语言，再限制文件名和目录
    "scope": "shellscript",
    "include": ["**/*.sh", "**/*.bash"],
    // 更具体的排除规则优先，避免污染生成文件
    "exclude": ["**/vendor/**", "**/*.generated.sh"],
    "body": [
      "#!/usr/bin/env bash",
      "# 片段示例：保留严格模式，按需补充脚本逻辑",
      "set -euo pipefail",
      "$0"
    ],
    "description": "只在 Shell 脚本中插入安全头部"
  }
}

文件名只有 *.sh 这类模式时，匹配的是文件名本身；写成 scripts/**/*.sh 这类路径模式时，才表达工作区内的目录关系。不要把搜索面板的“文件包含/排除”设置当成片段规则，它们是两个独立功能。

按匹配文件、排除文件和前缀验收

保存片段后，先打开 scripts/deploy.sh，确认状态栏语言为 Shell，执行“Insert Snippet”并搜索 Shell safe header，或者输入 shh 后按 Tab。然后依次打开 vendor/deploy.sh、scripts/build.generated.sh 和一个 .ts 文件，预期结果如下。

如果“Insert Snippet”里能看到名称但输入前缀没有提示，先检查 editor.tabCompletion 是否开启；如果连名称都搜不到，再回到语言标识和文件模式。全局片段文件不需要重启 VS Code，保存后即可重新打开片段选择器。

常见边界和修正顺序

最常见的误判有三个。第一，scope 写的是语言标识，不是显示名称，先从当前文件的语言模式确认值。第二，include 与 exclude 同时命中时排除优先，所以排除规则应写得具体，避免把整个脚本目录误伤。第三，文件名模式命中不代表片段一定显示，片段还要有可用的 prefix，并且不能被用户手动隐藏出 IntelliSense。

排查顺序建议固定为“语言模式 → 片段文件 → scope → include → exclude → prefix”。每改一个层级，就用一个匹配文件和一个排除文件复查，最后把验证过的模式写进项目说明，后续新增片段时直接沿用。

相关问题

没有写 include 时，片段会出现在哪里？

在语言范围已经满足的前提下，没有 include 就不会追加文件模式限制；如果也没有 exclude，片段会出现在该语言适用的文件中。

include 和 exclude 都匹配时哪个生效？

exclude 优先。可以用较宽的 include 覆盖目标目录，再用更具体的 exclude 排除生成文件或 vendor 文件。

为什么片段配置正确但按 Tab 没有展开？

先用 Insert Snippet 确认片段是否可见，再检查 prefix 和 editor.tabCompletion。如果片段可见但文件不匹配，优先检查语言模式与 glob，而不是修改 body。