Sublime的代码块注释模板必须做成.sublime-snippet文件并严格匹配scope(如source.js、source.vue meta.script.js),否则Tab失效;需用Developer: Show Scope Name查准scope,通过Tools: New Snippet创建,保存至Packages/User/目录,文件名以.sublime-snippet结尾;复杂场景推荐DocBlockr插件实现上下文感知注释。

Sublime 的代码块注释模板不是靠“写个 JSON 就生效”,而是必须做成 .sublime-snippet 文件,并严格匹配当前文件的 scope —— 否则按 Tab 就是静默失败。
为什么 /** + Tab 不生成注释?先查 scope 是不是对得上
Sublime 不认你右下角写的 “JavaScript” 或 “Vue”,它只认内部作用域名,比如 source.js、source.vue meta.script.js,甚至 source.tsx meta.jsx。错一个层级,片段就完全不触发。
- 把光标放在你想插入注释的位置(比如函数名前)
- 按
Ctrl+Shift+P(Win/Linux)或Cmd+Shift+P(macOS)→ 输入Developer: Show Scope Name回车 - 状态栏会显示一长串,例如
source.js meta.function.js→ 取最左边的主干source.js,或完整链都填进去 -
标签里写成,用英文逗号分隔source.js, source.tsx, source.vue meta.script.js
怎么写一个 /** 模板 snippet?别手写 XML
手动新建 .xml 文件再改后缀极易出错:漏 、编码声明不对、标签闭合错位都会导致整个 snippet 加载失败。
- 按
Ctrl+Shift+P→ 输入Tools: New Snippet回车,自动生成带注释的骨架 - 取消注释
,改成你想要的,比如log doc或fn(别用/**,含符号会解析失败) - 取消注释
,替换成你查到的实际 scopesource.python - 在
里写注释模板,例如:
/**
* ${1:description}
* @param {${2:type}} ${3:param}
* @returns {${4:type}}
*/
-
$1是第一个跳转位,${2:type}表示默认值为type,可编辑;$0必须显式写在末尾,否则光标卡死
保存路径和文件名有硬性要求
Sublime 只扫描特定目录下的 .sublime-snippet 文件,且文件名不能带空格、中文或多余点号。
- 保存路径必须是
Packages/User/(可通过Preferences → Browse Packages…进入) - 文件名必须以
.sublime-snippet结尾,例如fn-doc.sublime-snippet,写成fn-doc.snippet或fn-doc.sublime-snippet.txt都不加载 - 改完保存后无需重启 Sublime,但若之前已打开同名 snippet,要关掉重开才能热更新
- 如果多个 snippet 共享同一
tabTrigger(如都设了log),Sublime 只加载最先找到的那个,不会合并
想让 /** 自动出现在函数前?别依赖 snippet,用 DocBlockr
纯 snippet 做不了上下文感知——它不管光标前面有没有函数签名,只是机械插入。真要实现「在函数定义行上方敲 /** 回车就生成带参数的注释」,得用 DocBlockr 插件。
- 通过
Package Control安装DocBlockr - 配置
Preferences → Package Settings → DocBlockr → Settings - User,开启"auto_complete": true和"jsdoc_enable_types": true - 确保文件语法识别正确(
.vue文件里的<script></script>块需是source.vue meta.script.js,不是source.js) -
DocBlockr会自动提取函数参数名、类型(TS/JSdoc)、返回值,比手写 snippet 精准得多
真正容易被忽略的是 scope 的嵌套性:Vue 单文件组件、TSX、MDX 这些混合语法场景下,source.js 从来就不够用,必须用 Developer: Show Scope Name 实时看,而不是凭经验猜。











