sublime如何设置保存文件时自动添加文件头注释？（团队规范统一）

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 
class AutoFileHeaderListener(sublime_plugin.EventListener): def on_pre_save(self, view): if not self._should_inject(view): return
    # 读取模板     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 True
file_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 python3n# -*- 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 行必须顶格。这些细节没对齐，自动化就会变成新负担。