VS Code和PyCharm自动添加Python编码声明注释的设置方法

图 0：VS Code 与 PyCharm 编码声明与文件头自动化生成概览

一、PEP 263 规范与编码声明的解析原理

在深入配置之前，需要先明确 Python 解释器如何识别和处理源文件编码。根据官方规范 PEP 263，Python 解释器在读取源代码时，会使用正则表达式专门探测前两行的内容。若未声明编码，Python 2 会默认使用 ASCII，而 Python 3 虽然将默认源文件编码统一为 UTF-8，但在跨操作系统协作（如 Windows 简体中文默认代码页 cp936 与 Linux UTF-8 互通）、存在特殊字符注释或老旧工具链静态检查的场景下，显式指定编码声明依旧是保障语法解析一致性的标准工程实践。

解释器探测编码时遵循严格的行号扫描窗口：声明必须出现在源文件的第一行或第二行。如果第一行包含 UNIX 系统的执行解释器路径说明（即 Shebang #!/usr/bin/env python3），则编码声明必须放置在紧随其后的第二行。若编码声明出现在第 3 行及以后，或者其上方存在任何普通 Python 语句（如 import os），解释器将直接忽略该声明，仍然采用默认行为。

图 1：PEP 263 编码声明机制与行首扫描规则

在语法书写上，PEP 263 规定只要注释内容能够匹配正则 coding[:=][ ]*([-_.a-zA-Z0-9]+) 即可。最常见的标准写法包括 Emacs 兼容风格 # -*- coding: utf-8 -*- 与紧凑赋值风格 # coding=utf-8。工程实践中普遍优先推荐 Emacs 兼容风格，其识别度高、兼容性好且能被主流代码编辑器的高亮分析引擎准确捕获。

二、PyCharm 中全自动添加编码声明的设置步骤

PyCharm 作为全功能的 Python 集成开发环境，原生支持自定义“文件和代码模板”。完成此项配置后，每当在项目树中右键新建 Python 文件，IDE 就会自动把预置的编码声明及文件头直接注入到新建的文件内，完全不需要额外的按键或插件支持。

图 2：PyCharm 配置自动添加编码声明四步法

1. 打开设置对话框

在 PyCharm 界面中打开首选项设置窗口：

• Windows / Linux 平台：按快捷键 Ctrl + Alt + S，或点击顶部主菜单 File > Settings。
• macOS 平台：按快捷键 Cmd + ,，或点击屏幕左上角 PyCharm > Settings（或 Preferences）。

2. 定位文件模板配置项

在设置窗口左侧的搜索框中输入 File and Code Templates，或在导航树中依次展开 Editor（编辑器）> File and Code Templates（文件和代码模板）。

3. 编辑 Python Script 模板

在右侧区域切换到 Files（文件）标签页，在文件类型列表中找到并点击 Python Script。在中间的大文本编辑框中，输入所需的编码声明及头注释内容。例如：

#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
@Project : ${PROJECT_NAME}
@File    : ${NAME}.py
@Author  : ${USER}
@Date    : ${DATE} ${TIME}
"""

PyCharm 在模板引擎中支持 Apache Velocity 语法，上述示例中使用的预置变量解释如下：

• ${PROJECT_NAME}：当前项目的根工程名称。
• ${NAME}：新建文件时在弹窗中输入的文件名（不含 .py 后缀）。
• ${USER}：当前登录操作系统的用户名。
• ${DATE} 与 ${TIME}：生成文件时的当前系统日期与时间。

4. 保存配置与效果验证

点击右下角的 Apply（应用），然后点击 OK 退出设置窗口。回到工程项目目录树，鼠标右键点击任意目录，选择 New > Python File，输入测试文件名 demo 回车。打开新文件，即可看到第一行或第二行已经整整齐齐地带有 # -*- coding: utf-8 -*-。

三、VS Code 中配置自动添加的两种实现方案

与 PyCharm 这种重型 IDE 不同，VS Code 本身崇尚轻量架构，未在核心主干中捆绑强制的新建文件模板，但它提供了强大的“用户代码片段（User Snippets）”扩展机制；若追求完全免击键的静默插入，也可以配合轻量扩展完成。以下分别给出两种方案的实操路径。

图 3：VS Code 两种自动化添加方案架构与触发机制对比

方案一：官方原生用户代码片段（推荐，零插件依赖）

这是最干净、轻量且稳定可靠的方案。通过 VS Code 自带的 Snippets 功能，只需输入设定的简写并敲击 Tab 键，就能瞬间展开完整头部声明，并自动把光标精准定位到想要写代码的位置。

1. 打开代码片段配置：使用快捷键 Ctrl + Shift + P（macOS 为 Cmd + Shift + P）调出命令面板，输入 snippets，选择 Preferences: Configure User Snippets（首选项：配置用户代码片段）。
2. 选中 Python 配置文件：在下拉搜索列表中键入 python，回车打开 python.json 配置文件。
3. 填入代码片段规则：在打开的 JSON 文件内部大括号中，添加如下片段对象：

{
  "Python Encoding Header": {
    "prefix": "header",
    "body": [
      "#!/usr/bin/env python3",
      "# -*- coding: utf-8 -*-",
      """"",
      "@File    :   $TM_FILENAME",
      "@Author  :   $TM_USERNAME",
      "@Date    :   $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE $CURRENT_HOUR:$CURRENT_MINUTE:$CURRENT_SECOND",
      """"",
      "",
      "$0"
    ],
    "description": "自动插入 Python 编码声明与文件头注释"
  }
}

核心配置解析：

• prefix：触发片段补全的缩写词，这里设为 header（也可设为 py 或 ch）。
• $TM_FILENAME：VS Code 环境变量，自动获取当前文件名。
• $CURRENT_YEAR 等：自动读取系统当前年、月、日、时、分、秒。
• $0：光标停靠锚点。当模板展开后，编辑光标会直接落在 $0 所在位置，读者可以直接键入业务代码。

验证效果：在 VS Code 中新建一个 test.py 文件，在第 1 行输入 header，按键盘 Tab 键或回车，即可瞬间展开完整的编码声明与文件信息。

方案二：利用文件模板扩展实现新建自动静默插入

如果开发习惯强依赖“只要新建空文件，就必须立刻在文件中看到声明，一个键都不想多按”，可以借助 VS Code 社区成熟的文件头扩展（例如 koroFileHeader 或 File Templates）：

1. 在 VS Code 扩展面板（快捷键 Ctrl + Shift + X）中搜索并安装 koroFileHeader。
2. 打开 VS Code 设置（快捷键 Ctrl + , / Cmd + ,），点击右上角“打开设置 (JSON)”图标进入 settings.json。
3. 在配置中添加文件头自动生成规则：

"fileheader.customMade": {
  "custom_string_obk": [
    "#!/usr/bin/env python3",
    "# -*- coding: utf-8 -*-"
  ],
  "Description": "Python Source File",
  "Author": "Developer",
  "Date": "Do not edit",
  "LastEditTime": "Do not edit"
},
"fileheader.configObj": {
  "autoAdd": true,
  "createHeader": true
}

配置保存后，扩展会监听新文件创建事件 onDidCreateTextDocument，在新建 .py 文件时自动完成写入。

四、VS Code 与 PyCharm 方案对比与排错自检清单

为了让大家在不同的工作场景中快速做出合理选择，下表对两种工具及不同配置方案的关键指标进行了横向汇总：

图 4：VS Code 与 PyCharm 配置方案对比与排错检查清单

五、常见问题与排错注意事项

在配置和实际运行过程中，如果遇到编码声明未生效或报错，请按照以下几项关键排查点逐一对照：

1. 确保声明严格位于前两行：如前文原理部分所述，编码声明只能在第 1 行，或者在包含 #!/usr/bin/... 的第 2 行。如果在声明之前存在任何空行以外的代码、文档字符串（Docstring）或导包语句，Python 解释器在编译 AST 之前将直接跳过编码扫描，导致编码声明彻底失效。
2. 排查 UTF-8 BOM 干扰：在 Windows 平台下，部分早期文本编辑器默认会保存带有 BOM（Byte Order Mark）的 UTF-8 编码。BOM 会在文件开头注入不可见的 3 个字节 \xef\xbb\xbf。这不仅可能破坏 UNIX Shebang 的第一行识别，也可能导致部分静态扫描器报错。无论是 VS Code 还是 PyCharm，请确保底部状态栏显示的编码格式为纯正的 UTF-8 而非 UTF-8 with BOM。
3. VS Code 语言模式未识别：如果在 VS Code 中新建了一个未命名的空标签页（Untitled-1），右下角的语言模式若显示为 Plain Text（纯文本），此时在 python.json 中配置的代码片段将不会触发提示。解决方法是先保存文件命名为 .py 结尾，或者点击右下角将语言模式临时切换为 Python，即可正常唤出补全。
4. PyCharm 模板变量未解析：如果在生成的新文件中看到 ${DATE} 或 ${USER} 字样原样保留而未转换成实际时间或用户名，说明在模板中大括号书写存在语法格式错误，或者拼写了不支持的非法变量名。请仔细对照本文给出的标准模板变量列表进行校正。