VS Code snippets 代码片段如何创建并高效使用？

为什么要用 VS Code snippets

如果你经常重复写 console.log、React 组件、文件头注释、Python 类或者 HTML 模板，VS Code snippets 就很值得配置。它的作用很直接：输入一个短前缀，按下 Tab 或 Enter，就把一段常用代码插入到当前位置，并且让光标按顺序跳到需要修改的地方。

它适合解决两类问题：一类是减少重复输入，另一类是统一团队写法。比如每个人创建 React 组件时都按同一套 props、导出方式和文件头格式来写，后续维护会少很多无意义差异。

VS Code 代码片段存放在哪里

VS Code 的代码片段主要有三种范围，选择哪一种取决于你希望它给谁用、在哪些文件里生效。

类型	存放位置	适合场景
用户代码片段	VS Code 用户配置目录	只给自己用，跨项目生效
语言代码片段	针对 JavaScript、Python、HTML 等语言配置	只在某一种语言文件里提示
项目代码片段	项目下的 .vscode/*.code-snippets	团队共享，随仓库提交

个人习惯类片段放用户配置里就够了；团队约定类片段更建议放在项目的 .vscode 目录中，这样新人拉下仓库后也能直接使用。

如何创建 VS Code snippets

最常用的创建方式是通过 VS Code 菜单进入：

1. 打开命令面板或菜单：File > Preferences > Configure User Snippets
2. 选择一种语言，例如 javascript.json、typescriptreact.json、python.json
3. 如果要创建全局片段，选择 New Global Snippets file...
4. 如果要给当前项目共享，创建 .vscode/xxx.code-snippets
5. 按 JSON 格式写入片段并保存

一个最小可用的代码片段长这样：

json
{
  "Print Console Log": {
    "prefix": "log",
    "body": ["console.log($1);"],
    "description": "Insert console.log"
  }
}

保存后，在支持的文件里输入 log，选择提示项，按 Tab 或 Enter 即可展开。

代码片段的基本结构

一个 snippet 通常包含三个字段：

json
{
  "Snippet Name": {
    "prefix": "trigger",
    "body": [
      "code line 1",
      "code line 2"
    ],
    "description": "Snippet description"
  }
}

• Snippet Name：片段名称，主要给自己识别用。
• prefix：触发前缀，可以是字符串，也可以是数组。
• body：真正插入的代码，多行时用数组更清晰。
• description：提示列表里展示的说明，建议写得具体一点。

如果一个片段有多个触发词，可以这样写：

json
{
  "Console Log": {
    "prefix": ["log", "clg"],
    "body": "console.log($1);",
    "description": "Insert console.log"
  }
}

前缀不宜太长，也不宜和语言关键字冲突。比如 class 虽然好记，但在 Python 或 JavaScript 里很容易和正常输入打架，团队项目里可以用 pyclass、rfc、useeffect 这类更明确的前缀。

占位符和光标跳转怎么写

占位符是 snippets 最有用的部分。$1、$2 表示光标跳转顺序，$0 表示最后停留的位置。

json
{
  "Function Template": {
    "prefix": "func",
    "body": [
      "function ${1:functionName}(${2:parameters}) {",
      "\t$0",
      "}"
    ],
    "description": "Create a function"
  }
}

展开后，光标会先选中 functionName，按 Tab 跳到 parameters，最后停在函数体内。${1:functionName} 里的 functionName 是默认文本，可以直接覆盖。

相同编号的占位符会同步修改，适合组件名、类名这类需要出现多次的内容：

json
{
  "Named Export Function": {
    "prefix": "nef",
    "body": [
      "export function ${1:handler}(${2:params}) {",
      "\treturn ${1:handler}Result;",
      "}"
    ],
    "description": "Create named exported function"
  }
}

这里两处 ${1:handler} 会一起变化，少一次手动改名，也少一次拼写错误。

Choice 选项适合写固定分支

如果某个位置只允许几种固定值，可以用 choice 占位符：

json
{
  "Console Statement": {
    "prefix": "console",
    "body": [
      "console.${1|log,warn,error,info|}($2);"
    ],
    "description": "Insert console statement"
  }
}

展开后，第一个位置会出现 log、warn、error、info 选项。它很适合日志级别、HTTP 方法、组件状态、CSS display 值这类内容。

常用变量怎么用

VS Code snippets 支持预定义变量，可以读取当前文件名、路径、日期、剪贴板等信息。

json
{
  "File Header": {
    "prefix": "header",
    "body": [
      "// File: ${TM_FILENAME}",
      "// Author: ${TM_USERNAME}",
      "// Date: ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}",
      "",
      "$0"
    ],
    "description": "Insert file header comment"
  }
}

常用变量包括：

变量	含义
TM_FILENAME	当前文件名，包含扩展名
TM_FILENAME_BASE	当前文件名，不包含扩展名
TM_DIRECTORY	当前文件目录
TM_FILEPATH	当前文件完整路径
CLIPBOARD	剪贴板内容
CURRENT_YEAR	当前年份
CURRENT_MONTH	当前月份
CURRENT_DATE	当前日期

有些变量取不到值时，VS Code 会把它当作普通占位符处理，所以写完后最好在真实文件里展开一次，确认效果符合预期。

JavaScript 和 TypeScript 片段示例

React 项目里，组件模板是最常见的 snippet。下面这个例子保留了组件名复用、props 类型和默认导出：

json
{
  "React TypeScript Component": {
    "prefix": "rfc",
    "body": [
      "import React from 'react';",
      "",
      "interface ${1:ComponentName}Props {",
      "\t${2:prop}: ${3:type};",
      "}",
      "",
      "const ${1:ComponentName}: React.FC<${1:ComponentName}Props> = ({ ${2:prop} }) => {",
      "\treturn (",
      "\t\t<div>",
      "\t\t\t${4:content}",
      "\t\t</div>",
      "\t);",
      "};",
      "",
      "export default ${1:ComponentName};",
      "$0"
    ],
    "description": "Create React functional component with TypeScript"
  }
}

实际项目里可以按团队规范调整，比如是否使用 React.FC、是否默认导出、是否引入样式文件。不要把模板写成唯一正确答案，snippet 应该服务于项目习惯。

Python 片段示例

Python 类模板可以把类名、文档字符串和初始化参数都做成占位符：

json
{
  "Python Class": {
    "prefix": "pyclass",
    "body": [
      "class ${1:ClassName}:",
      "\t\"\"\"${2:Class description}\"\"\"",
      "",
      "\tdef __init__(self${3:, args}):",
      "\t\t${4:pass}",
      "\t\t$0"
    ],
    "description": "Create Python class template"
  }
}

注意缩进建议用 \t，VS Code 会按当前文件的缩进配置转换。团队如果强制空格缩进，也可以直接写空格，但不同编辑器设置下更容易不一致。

HTML 片段示例

HTML5 模板适合放在 HTML 语言片段里：

json
{
  "HTML5 Boilerplate": {
    "prefix": "html5",
    "body": [
      "<!DOCTYPE html>",
      "<html lang=\"zh-CN\">",
      "<head>",
      "\t<meta charset=\"UTF-8\">",
      "\t<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">",
      "\t<title>${1:Page Title}</title>",
      "</head>",
      "<body>",
      "\t${2:content}",
      "</body>",
      "</html>"
    ],
    "description": "Create HTML5 boilerplate"
  }
}

如果你经常写中文页面，把 lang 默认成 zh-CN 会比复制英文模板后再改更省心。

Transform 转换能处理文件名

Transform 可以对变量或占位符做正则转换。它不适合写太复杂的逻辑，但用来处理文件名大小写很方便。

json
{
  "Import Current File Name": {
    "prefix": "impfile",
    "body": [
      "import { ${TM_FILENAME_BASE/(.*)/${1:/capitalize}/} } from './${TM_FILENAME_BASE}';"
    ],
    "description": "Import with transformed file name"
  }
}

如果文件名是 button.ts，展开后会得到类似：

ts
import { Button } from './button';

Transform 的语法可读性一般，建议只在收益明显时使用。复杂到需要反复解释的转换，不如写一个更直白的片段，维护成本更低。

全局代码片段怎么共享

全局片段文件通常命名为 global.code-snippets，可以在所有语言里生效。适合放 TODO、版权注释、通用注释块这类不依赖具体语言的模板。

json
{
  "TODO Comment": {
    "prefix": "todo",
    "body": [
      "// TODO: ${1:description} - ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}"
    ],
    "description": "Insert TODO comment with date"
  }
}

但要注意，通用片段不一定适合所有语言。上面的 // 注释在 JavaScript、TypeScript、Go 里没问题，在 HTML 或 CSS 中就不合适。如果要跨语言使用，最好把前缀和描述写清楚，避免误触。

项目代码片段更适合团队规范

如果片段和某个仓库强相关，建议放到项目里：

text
.vscode/
  project.code-snippets

示例：

json
{
  "Project API Handler": {
    "prefix": "api-handler",
    "body": [
      "export async function ${1:handlerName}(req: Request) {",
      "\ttry {",
      "\t\t${2:// handle request}",
      "\t} catch (error) {",
      "\t\t${3:// handle error}",
      "\t}",
      "}"
    ],
    "description": "Create project API handler"
  }
}

这类片段可以和代码审查规则配合起来：模板里提前放好错误处理、日志字段、命名约定，少靠口头提醒。

使用时容易踩的坑

JSON 转义写错

片段文件是 JSON。双引号要转义，反斜杠也要转义。比如 HTML 属性里的引号要写成 \"，换行不要直接写在字符串中，多行内容用数组更稳。

前缀和已有补全冲突

如果 prefix 太短，可能被变量名、关键字、Emmet 或语言服务补全淹没。团队片段最好用有辨识度的前缀，例如 rfc、api-handler、pyclass。

片段没有出现

可以按顺序检查：

1. 当前文件语言模式是否正确，比如 .tsx 是否识别为 TypeScript React。
2. snippet 是否写在对应语言文件或全局文件中。
3. JSON 是否有语法错误。
4. editor.snippetSuggestions 是否被关闭或排序靠后。
5. 当前输入位置是否允许代码补全。

项目片段和用户片段重复

当项目片段和用户片段前缀相同，提示列表里可能出现多个相似项。团队项目中最好约定前缀命名，个人片段避免覆盖团队片段。

不要期待片段自动调用另一个片段

VS Code snippets 本身不是宏系统，不能可靠地在一个 snippet 里自动展开另一个 snippet。可以把公共部分复制进模板，或者通过扩展、任务脚本解决更复杂的生成需求。

什么时候不该用 snippets

代码片段适合静态模板，不适合复杂生成逻辑。如果你需要根据接口定义生成类型、批量创建文件、读取项目配置再输出代码，脚手架或代码生成器更合适。

一个简单判断是：只替换几个名称、参数、路径，用 snippets；需要计算、读取文件或跨目录生成，用脚本工具。

写好 VS Code snippets 的几个原则

• 把最常改的内容做成 $1、$2，不要让光标在模板里来回找。
• 重复出现的名称使用同一个占位符编号，减少手动同步。
• description 写清楚用途，尤其是团队共享片段。
• 片段要短而准，不要把一整套业务逻辑塞进去。
• 保存后在真实文件里试一次，确认缩进、引号、Tab 跳转都正常。

VS Code snippets 的价值不在于写出多花哨的语法，而是把每天重复输入、容易写错、团队需要统一的代码固定下来。配置几条真正高频的片段，通常比收藏一大堆用不上的模板更有效。