Sublime Text需通过自定义Python插件实现保存时自动插入文件头，监听on_pre_save事件，检查文件类型与已有注释，从JSON模板加载并替换{author}、{date}后插入首行。
Sublime Text 本身不内置「保存时自动插入文件头」功能，必须通过插件 + 自定义配置实现。直接改 Preferences → Settings 不起作用，也别指望靠 save_on_focus_lost 触发脚本——它不支持逻辑判断和模板渲染。
用 SublimeCodeIntel + 自定义 Python 插件最可靠
官方推荐的 FileHeader 插件已多年未维护，兼容性差；DocBlockr 只处理函数注释。实际验证下来，最稳的方式是写一个轻量 Python 插件，监听 on_pre_save 事件，在文件为空或顶部无注释时自动注入。
- 插件路径：
Packages/User/auto_file_header.py（在 Sublime 中按Ctrl+Shift+P→Package Control: Create Plugin快速生成） - 只对指定后缀生效，比如
.py、.js、.ts，避免误触配置文件或二进制文件 - 检查是否已有注释：用正则匹配开头 3 行内是否存在
/**、# -*-、/*、//等常见头部标记 - 模板从
Packages/User/file_header_template.json加载，方便团队统一维护，不用硬编码在插件里
import sublime
import sublime_plugin
import json
import os
import re
<p>class AutoFileHeaderListener(sublime_plugin.EventListener):
def on_pre_save(self, view):
if not self._should_inject(view):
return</p><pre class='brush:php;toolbar:false;'> # 读取模板
template_path = os.path.join(sublime.packages_path(), "User", "file_header_template.json")
if not os.path.exists(template_path):
return
try:
with open(template_path, 'r', encoding='utf-8') as f:
data = json.load(f)
ext = view.file_name().split('.')[-1].lower()
tpl = data.get(ext) or data.get('default', '')
if not tpl:
return
except Exception:
return
# 插入到第一行
region = sublime.Region(0, 0)
view.insert(edit, 0, tpl + '\n')
def _should_inject(self, view):
fname = view.file_name()
if not fname:
return False
ext = fname.split('.')[-1].lower()
if ext not in ['py', 'js', 'ts', 'java', 'go']:
return False
content = view.substr(sublime.Region(0, min(view.size(), 200)))
if re.search(r'^(#|//|/\*|\*\s*@\w+)', content, re.MULTILINE):
return False
return Truefile_header_template.json 模板格式要严格匹配语言习惯
不同语言的注释语法、字符宽度、作者字段占位符都不同。模板里不能写死人名或日期，得用 {date}、{author} 这类占位符，再由插件运行时替换——否则每次保存都会覆盖原内容。
-
js模板必须用/** */块注释，且首行空行不能少，否则 ESLint 报spaced-comment -
py模板要保留# -*- coding: utf-8 -*-位置，通常放在第 2 行，第 1 行留给 shebang（如需） - 所有模板末尾加一个空行，避免和后续代码粘连
- 日期格式统一用
%Y-%m-%d，避免团队成员系统 locale 不一致导致格式错乱
{
"default": "/*\n * @Author: {author}\n * @Date: {date}\n */",
"py": "#!/usr/bin/env python3\n# -*- coding: utf-8 -*-\n#\n# @Author: {author}\n# @Date: {date}\n",
"js": "/**\n * @Author: {author}\n * @Date: {date}\n */"
}保存时自动填充作者和日期的关键是环境变量 + 用户设置
不能让每个成员手动改插件代码填名字，也不该从 Git 配置读（容易和提交者混淆）。最佳实践是让 Sublime 读取操作系统级环境变量，再 fallback 到 Preferences → Settings – User 里的 file_header_author 字段。
- Linux/macOS 下执行：
export SUBLIME_AUTHOR="张三"，并确保 Sublime 是从终端启动（subl .），否则 GUI 启动不继承 shell 环境 - Windows 用户在系统属性 → 高级 → 环境变量中添加
SUBLIME_AUTHOR - 在
Preferences.sublime-settings中加一行："file_header_author": "李四"，作为兜底 - 日期一律用
time.strftime('%Y-%m-%d')，不调用datetime.now()，避免时区解析歧义
真正难的不是写插件，而是让模板和占位符替换逻辑能覆盖团队里所有边缘情况：比如 TypeScript 文件带 JSX、Python 脚本带多行 docstring、Java 接口文件要求 @Copyright 行必须顶格。这些细节没对齐，自动化就会变成新负担。
