Quartz 4

文件编码最佳实践 - 避免乱码

9 min read

概述

本文档说明如何确保 Digital Garden 笔记始终使用正确的编码（UTF-8），避免出现乱码问题。

问题背景

常见乱码原因

  1. 编码不一致: 不同编辑器使用不同的默认编码
  2. 行尾符差异: Windows (CRLF) vs Linux (LF)
  3. BOM 问题: UTF-8 with BOM vs UTF-8 without BOM
  4. Git 配置: 未正确配置文本文件处理规则

为什么选择 UTF-8

  • ✅ 支持所有语言字符（中文、英文、emoji等）
  • ✅ 兼容 ASCII
  • ✅ Web 标准编码
  • ✅ 跨平台兼容性最好

项目配置

1. EditorConfig 配置

项目根目录的 .editorconfig 文件确保所有编辑器使用统一配置：

# .editorconfig
root = true
 
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
 
[*.md]
charset = utf-8
end_of_line = lf
trim_trailing_whitespace = false

支持的编辑器:

  • VS Code（内置支持）
  • Obsidian（通过插件）
  • JetBrains IDEs（内置支持）
  • Sublime Text（通过插件）

2. Git Attributes 配置

.gitattributes 文件确保 Git 正确处理文本文件：

# 自动检测文本文件并规范化行尾
* text=auto eol=lf
 
# Markdown 文件统一使用 LF 行尾，UTF-8 编码
*.md text eol=lf

作用:

  • 提交时自动转换行尾符为 LF
  • 检出时根据操作系统决定行尾符
  • 防止不同平台协作时出现行尾符混乱

3. VS Code 配置

.vscode/settings.json 为 VS Code 用户提供默认配置：

{
  "files.encoding": "utf8",
  "files.autoGuessEncoding": false,
  "files.eol": "\n",
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true
}

编辑器设置

VS Code

  1. 全局设置（推荐）

    • 打开设置: Ctrl/Cmd + ,
    • 搜索 “encoding”
    • 设置 Files: Encoding 为 utf8
    • 设置 Files: Eol 为 \n (LF)

  2. 检查当前文件编码

    • 查看状态栏右下角显示的编码
    • 点击可切换编码

  3. 重新打开文件以指定编码

    • 命令面板: Ctrl/Cmd + Shift + P
    • 输入 “Reopen with Encoding”
    • 选择 “UTF-8”

Obsidian

Obsidian 默认使用 UTF-8 编码，但可以安装插件增强支持：

  1. 安装 EditorConfig 插件

    • 设置 → 社区插件 → 浏览
    • 搜索 “EditorConfig”
    • 安装并启用

  2. 检查设置

    • 设置 → 编辑器
    • 确认默认编码为 UTF-8

记事本++（Windows）

  1. 默认编码设置

    • 设置 → 首选项 → 新建
    • 编码: UTF-8
    • 格式: Unix (LF)

  2. 转换现有文件

    • 编码 → 转换为 UTF-8（无BOM）
    • 编辑 → 行尾符格式 → Unix (LF)

检查和修复工具

编码检查脚本

项目提供了自动检查脚本：

# 检查所有 Markdown 文件编码
.\scripts\check-encoding.ps1
 
# 自动修复非 UTF-8 编码的文件
.\scripts\check-encoding.ps1 -Fix

脚本功能:

  • 扫描所有 .md 文件
  • 检测编码类型（UTF-8, UTF-8-BOM, UTF-16等）
  • 可选自动转换为 UTF-8（无BOM）

手动检查方法

PowerShell 检查单个文件

# 方法1: 使用 Get-Content
Get-Content -Path "file.md" -Encoding UTF8 -Raw
 
# 方法2: 检查 BOM
$bytes = [System.IO.File]::ReadAllBytes("file.md")
if ($bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
    Write-Host "UTF-8 with BOM"
} else {
    Write-Host "UTF-8 without BOM or other encoding"
}

Bash/Linux 检查

# 使用 file 命令
file -i content/**/*.md
 
# 使用 chardet（需要安装）
chardet content/**/*.md
 
# 查找非 UTF-8 文件
find content -name "*.md" -exec file -i {} \; | grep -v "utf-8"

Git 配置

全局配置

# 设置默认编码为 UTF-8
git config --global core.quotePath false
git config --global gui.encoding utf-8
git config --global i18n.commit.encoding utf-8
git config --global i18n.logOutputEncoding utf-8
 
# Windows 用户额外配置
git config --global core.autocrlf false
git config --global core.safecrlf warn

配置说明

  • core.quotePath false: 显示中文文件名
  • core.autocrlf false: 不自动转换行尾符（由 .gitattributes 控制）
  • core.safecrlf warn: 检测混合行尾符时警告

最佳实践

创建新笔记

  1. 使用支持 UTF-8 的编辑器

    • ✅ VS Code、Obsidian、Typora
    • ⚠️ 避免使用 Windows 记事本（默认 ANSI）

  2. 模板设置

    ---
title: 笔记标题
date: 2026-01-02
---
 
笔记内容...

  3. 保存时检查

    • 确认编辑器状态栏显示 UTF-8
    • 确认行尾符为 LF

编辑现有笔记

  1. 打开文件前检查编码

  2. 如果编码错误:

    • VS Code: “Reopen with Encoding” → UTF-8
    • 或使用检查脚本自动修复

  3. 保存后验证

    git diff
# 查看是否有意外的编码更改

复制粘贴内容

  • ✅ 从 Web 页面复制: 通常是 UTF-8
  • ✅ 从其他 UTF-8 文件复制: 安全
  • ⚠️ 从 Word/Excel 复制: 可能包含特殊字符
  • ⚠️ 从旧系统复制: 检查编码

提交前检查

# 1. 运行编码检查
.\scripts\check-encoding.ps1
 
# 2. 查看 Git 差异
git diff
 
# 3. 确认没有编码问题后提交
git add .
git commit -m "描述信息"

常见问题排查

问题 1: 中文显示为乱码

原因: 文件不是 UTF-8 编码

解决:

# 自动修复
.\scripts\check-encoding.ps1 -Fix
 
# 手动修复
# VS Code: File → Save with Encoding → UTF-8

问题 2: 提交后在 GitHub 显示乱码

原因:

  • Git 未正确处理文本文件
  • 文件实际不是 UTF-8

解决:

# 1. 检查 .gitattributes 是否生效
git check-attr text content/path/to/file.md
 
# 2. 重新规范化文件
git add --renormalize .
git commit -m "fix: normalize line endings"
 
# 3. 如果还有问题，强制转换
.\scripts\check-encoding.ps1 -Fix
git add .
git commit -m "fix: convert to UTF-8 encoding"

问题 3: 不同编辑器打开显示不同

原因: 编辑器自动检测编码错误

解决:

  1. 统一使用 .editorconfig
  2. 在 VS Code 中打开并保存（强制 UTF-8）
  3. 运行检查脚本验证

问题 4: Emoji 或特殊符号无法显示

原因:

  • 编码不是 UTF-8
  • 字体不支持该符号

解决:

# 1. 确认文件是 UTF-8
.\scripts\check-encoding.ps1
 
# 2. 更换编辑器字体
# VS Code: 设置 → Font Family
# 推荐: "Cascadia Code", "Fira Code", "JetBrains Mono"

问题 5: Git 提示行尾符警告

原因: 文件混合了 CRLF 和 LF

解决:

# 1. 检查文件
git diff --check
 
# 2. 让 Git 自动修复
git add --renormalize .
 
# 3. 或手动统一
# VS Code: 右下角点击 CRLF → 选择 LF
# 全选 → Save

CI/CD 集成

在部署脚本中添加检查

修改 deploy.ps1:

# 部署前检查编码
Write-Info "Checking file encodings..."
.\scripts\check-encoding.ps1
if ($LASTEXITCODE -ne 0) {
    Write-Error "Encoding check failed!"
    exit 1
}

GitHub Actions 示例

name: Check Encoding
 
on: [push, pull_request]
 
jobs:
  check:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check file encoding
        run: .\scripts\check-encoding.ps1
        shell: pwsh

工具推荐

编辑器

编辑器UTF-8 支持EditorConfig推荐度
VS Code✅ 优秀✅ 内置⭐⭐⭐⭐⭐
Obsidian✅ 优秀✅ 插件⭐⭐⭐⭐⭐
Typora✅ 优秀❌ 无⭐⭐⭐⭐
Sublime Text✅ 良好✅ 插件⭐⭐⭐⭐
Notepad++✅ 良好✅ 插件⭐⭐⭐
Windows 记事本⚠️ 较差❌ 无⭐

命令行工具

# 安装 chardet（Python）
pip install chardet
 
# 安装 iconv（Linux/Mac）
brew install libiconv  # Mac
sudo apt-get install libc-bin  # Linux
 
# Windows 自带 PowerShell（推荐）

参考资源

快速检查清单

在创建或编辑笔记时，确保：

  • 编辑器设置为 UTF-8 编码
  • 行尾符设置为 LF
  • 保存前检查状态栏编码显示
  • 提交前运行 .\scripts\check-encoding.ps1
  • Git diff 没有意外的编码更改
  • 中文和特殊字符正常显示

相关文档

更新记录

  • 2026-01-02: 创建文档，添加编码检查脚本和配置文件

Graph View

Backlinks