VSCode本身不自动注入文件头注释，必须依赖User Snippets手动触发或KoroFileHeader等扩展实现新建文件时自动插入；Snippets最轻量但需手动输入prefix（如header）+Tab，且须确保光标不在首行以避免覆盖编码声明。
VSCode 本身不自动注入文件头注释，必须靠 User Snippets 手动触发，或借助扩展（如 KoroFileHeader、File Header Comments）实现新建文件时自动插入。纯 Snippets 方案最轻量、可控性最强，但无法“全自动”——这是设计使然，不是配置错了。
怎么用 User Snippets 插入 Python 文件头
核心是编辑 python.json，定义一个带变量的 body。注意：文件头必须放在编码声明（如 # -*- coding: utf-8 -*-）之后，否则会被 Python 解释器忽略。
在命令面板输入 Preferences: Configure User Snippets → 选择 python → 添加如下片段：
{
"Python File Header": {
"prefix": "header",
"body": [
"\"\"\"",
"Author: ${1:Your Name}",
"Date: ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}",
"FileName: ${TM_FILENAME}",
"Description: ${2:brief description}",
"\"\"\"",
"",
"${3:def main():}",
" ${4:pass}",
"",
"if __name__ == \"__main__\":",
" ${5:main()}"
],
"description": "Insert standard Python file header"
}
}
-
${TM_FILENAME}是当前文件名，不是路径；若需路径用${TM_FILEPATH} -
$1、$2是光标跳转位，Tab 键依次切换；$0可设为最终位置（比如放在if __name__ == ...后） - 保存后无需重启 VSCode，新开一个
.py文件，输入header+ Tab 即可展开 - 如果没反应，检查右下角语言模式是否为
Python（不是Plain Text）
为什么 header 片段有时插在文件最顶上，破坏了编码声明？
因为 Snippets 不管上下文，只按光标位置插入。如果你把光标停在第一行就触发 header，它就会插在最上面。
- 正确做法：先写好编码声明行（如
# -*- coding: utf-8 -*-），再换行，把光标移到第二行开头，再输入header - 更稳妥的方式：在
body开头加一个空行，强制留出编码声明的位置（如["", "\"\"\"", ...]） - Snippets 没有“检测已有编码声明并智能跳过”的能力，这点必须手动兜底
想让新建文件时自动加头？别硬套 Snippets
User Snippets 是手动触发机制，强行让它“自动”只会失败。真要自动，得用扩展：
-
KoroFileHeader：配置fileheader.configObj和fileheader.cursorMode，支持 Git 用户名读取、自定义模板、保存时更新时间 -
File Header Comments：启用autoinsertoncreate，配合author、date等变量，但作者名需手动填进settings.json - 两者都依赖
files.associations正确识别文件类型（比如*.py必须关联到python） - 混用 Snippets 和自动扩展容易冲突——比如你手动输
header，扩展又在保存时追加一遍，导致重复注释
真正难的不是写对 JSON，而是决定哪些信息该动态生成（如日期）、哪些该固定（如公司版权声明），以及团队里所有人是否统一用了同一套变量名和缩进风格。一旦项目里出现 ${author} 和 ${AUTHOR} 并存，后续维护成本会指数上升。
