vscode-gbk2utf8 用户手册

vscode-gbk2utf8 是一款用于将文本文件转换为 UTF-8 编码的 VS Code 插件。它适合处理历史项目、中文旧编码文件、跨平台协作文件，以及需要批量统一编码的文本资源。

主要功能

• 将单个文本文件转换为 UTF-8。
• 支持在资源管理器中多选文件后批量转换。
• 支持选择文件夹，并递归转换文件夹中的文本文件。
• 转换前自动创建 .bak 备份文件。
• 自动识别常见来源编码。
• 自动跳过已经是 UTF-8 的文件。
• 自动跳过图片、压缩包、可执行文件等二进制文件。
• 转换完成后显示成功、跳过、失败数量。
• 可在输出面板中查看详细转换日志。

适用场景

• 项目中存在 GBK、GB2312、Big5 等旧编码文本文件。
• 打开文件时出现中文乱码。
• 需要将一批源码、配置文件、日志文件统一转换为 UTF-8。
• 需要在提交代码前统一项目文本编码。

安装插件

1. 打开 VS Code。
2. 进入扩展面板。
3. 搜索 vscode-gbk2utf8。
4. 点击 Install 安装。
5. 安装完成后无需额外配置，即可在资源管理器右键菜单中使用。

基本使用

转换单个文件

1. 在 VS Code 资源管理器中找到需要转换的文本文件。
2. 右键该文件。
3. 点击 转换为 UTF-8。
4. 等待转换完成通知。
5. 如需查看详情，点击通知中的 查看详情。

转换成功后，原文件会被写回为 UTF-8 编码，并在同目录下生成备份文件。

示例：

example.txt
example.txt.bak

批量转换多个文件

1. 在 VS Code 资源管理器中按住 Ctrl 或 Shift 多选文件。
2. 右键已选中的文件。
3. 点击 转换为 UTF-8。
4. 等待批量转换完成。

插件会逐个处理所选文件。某个文件失败不会影响其他文件继续转换。

转换文件夹

1. 在 VS Code 资源管理器中右键一个文件夹。
2. 点击 转换为 UTF-8。
3. 插件会递归扫描该文件夹中的文本文件。
4. 转换完成后会显示处理结果摘要。

默认会跳过以下目录：

.git
node_modules
.vscode
dist
build
out

转换结果说明

转换完成后，VS Code 会显示类似以下提示：

UTF-8 转换完成：成功 12，跳过 5，失败 1

含义如下：

• 成功：文件已成功转换为 UTF-8。
• 跳过：文件无需转换或不适合转换，例如已是 UTF-8、二进制文件、超过大小限制、编码识别置信度较低。
• 失败：处理文件时发生错误，例如文件无法读取、备份失败、写入失败。

查看详细日志

转换完成后，可以点击通知中的 查看详情。

也可以手动打开：

View -> Output

然后在输出面板右侧下拉框中选择：

vscode-gbk2utf8

日志会展示每个文件的处理状态、来源编码、备份路径和失败原因。

备份与恢复

插件默认会在转换前创建备份文件。

例如转换：

readme.txt

会生成：

readme.txt.bak

如果同名备份已经存在，会自动递增：

readme.txt.bak.1
readme.txt.bak.2

如果转换结果不符合预期，可以删除转换后的文件，并将 .bak 文件改回原文件名。

插件设置

可以在 VS Code 设置中搜索 vscode-gbk2utf8 修改配置。

vscode-gbk2utf8.backupBeforeConvert

默认值：true

是否在转换前创建 .bak 备份文件。

vscode-gbk2utf8.recursiveFolder

默认值：true

右键文件夹转换时，是否递归处理子文件夹。

vscode-gbk2utf8.excludeDirs

默认值：

[
  ".git",
  "node_modules",
  ".vscode",
  "dist",
  "build",
  "out"
]

文件夹转换时需要跳过的目录名。

vscode-gbk2utf8.addBom

默认值：false

是否写入 UTF-8 BOM。默认输出 UTF-8 without BOM。

vscode-gbk2utf8.maxFileSizeMB

默认值：20

超过该大小的文件会被跳过，避免误处理大型文件。

支持的文件类型

插件会优先处理常见文本文件，例如：

.txt
.md
.json
.js
.ts
.css
.html
.xml
.csv
.yml
.yaml
.ini
.log
.py
.java
.go
.rs
.vue
.svelte
.sql

对于未知扩展名的文件，插件会读取文件前部内容并判断是否像文本文件。如果检测到明显二进制内容，会自动跳过。

编码识别说明

插件会自动识别来源编码，并将文本内容写回为 UTF-8。

可能识别的常见编码包括：

GBK
GB2312
Big5
UTF-16LE
UTF-16BE
Shift-JIS
ISO-8859-1

如果编码识别置信度较低，插件会跳过该文件，避免错误转换导致内容损坏。

注意事项

• 建议首次批量转换前确认已经开启备份。
• 建议先在小范围文件夹中试用，再处理大型项目。
• 插件不会主动统一换行符，原文件中的 CRLF 或 LF 会随文本内容保留。
• 插件默认不会给 UTF-8 文件添加 BOM。
• 插件主要面向本地文件使用。

常见问题

为什么有些文件被跳过？

常见原因包括：

• 文件已经是 UTF-8。
• 文件不是文本文件。
• 文件超过大小限制。
• 文件位于排除目录中。
• 插件无法可靠识别来源编码。

可以在 vscode-gbk2utf8 输出面板中查看具体原因。

为什么短文本文件没有被转换？

非常短的文本可能缺少足够的编码特征，自动识别结果不可靠。为了避免损坏文件，插件会跳过低置信度识别结果。

转换后发现内容不对怎么办？

默认情况下，插件会在转换前生成 .bak 备份文件。可以使用备份文件恢复原内容。

可以关闭备份吗？

可以。将 vscode-gbk2utf8.backupBeforeConvert 设置为 false 即可。

不建议在批量转换时关闭备份。

可以只转换当前文件夹，不递归子文件夹吗？

可以。将 vscode-gbk2utf8.recursiveFolder 设置为 false 即可。

反馈问题

如果遇到无法转换、转换结果异常或希望支持更多编码场景，请在插件 Marketplace 页面或项目仓库中提交反馈，并尽量提供以下信息：

• VS Code 版本。
• 操作系统。
• 文件原始编码。
• 文件扩展名。
• 输出面板中的错误信息。