Docs Hub

主题

好学云谱 · 开发规范 ​

UTF-8 编码规则 ​

本项目所有源码、文档、配置、测试脚本和生成模板均统一使用 UTF-8。中文乱码通常来自 Windows PowerShell / 重定向 / 脚本写文件时使用了系统默认编码，开发时必须遵守以下规则。

必须遵守 ​

  • 所有新增文件必须保存为 UTF-8，不要使用 ANSI、GBK、GB2312。
  • 编辑器必须尊重根目录 .editorconfig：charset = utf-8、end_of_line = lf。
  • PowerShell 查看中文文件时使用：
powershell
Get-Content -Encoding UTF8 -Path README.md
  • PowerShell 写入中文文件时必须显式指定 UTF-8：
powershell
Set-Content -Encoding UTF8 -Path docs\example.md -Value $text
Add-Content -Encoding UTF8 -Path docs\example.md -Value $line
  • Node.js 读写文本文件时必须显式使用 utf8：
js
import fs from "node:fs/promises";

const text = await fs.readFile("README.md", "utf8");
await fs.writeFile("docs/example.md", text, "utf8");
  • 自动化脚本、Codex、批处理或一次性修复脚本只要会读写中文文件，也必须显式指定 UTF-8 / utf8。不要依赖系统默认编码。
  • 修改中文源码时优先使用项目内已有编辑工具或补丁方式，避免用终端重定向直接覆盖整文件。
  • 浏览器页面必须保留：
html
<meta charset="UTF-8" />
  • HTTP 返回 HTML、CSS、JS、JSON、Markdown 时应带 UTF-8 charset，例如：
http
Content-Type: text/html; charset=utf-8

禁止事项 ​

  • 不要用未指定编码的 PowerShell 命令重写中文文件。
  • 不要用 Out-File / > / >> 直接生成含中文的源码或文档，除非已经明确当前环境输出为 UTF-8，并经过验证。
  • 不要用 cmd /c echo 中文 > file、批处理重定向、未声明编码的 Python/Node 临时脚本覆盖中文文件。
  • 不要把终端里显示的乱码复制回源码文件。
  • 不要混用 GBK/ANSI 文件作为模板。

Windows 终端建议 ​

如果 PowerShell 中查看中文出现乱码，先切换控制台代码页：

powershell
chcp 65001
$OutputEncoding = [System.Text.UTF8Encoding]::new()
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new()
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()

注意：chcp 65001 只影响终端显示，不等于文件已经是 UTF-8。文件写入仍需显式指定 -Encoding UTF8。

提交流程检查 ​

修改含中文的文件后，至少做一次 UTF-8 读取检查：

powershell
Get-Content -Encoding UTF8 -Path js\views\login.js | Select-Object -First 20

若看到类似 浜戣氨、璋卞、鐧诲綍 的文本，说明文件内容或读取方式可能已经乱码，需要立刻停止继续编辑，回到最近正常版本重新处理。

打包或发布前建议抽查关键中文文件：

powershell
Get-Content -Encoding UTF8 -Path README.md | Select-Object -First 5
Get-Content -Encoding UTF8 -Path docs\开发规范.md | Select-Object -First 20
Get-Content -Encoding UTF8 -Path js\views\login.js | Select-Object -First 20
Get-Content -Encoding UTF8 -Path js\views\documents.js | Select-Object -First 20

如果需要在 PowerShell 中批量检查疑似乱码，可先搜索常见 mojibake 片段：

powershell
rg "浜|璋|鐧|绠|Ã|Â|�" README.md docs js css index.html service-worker.js

搜索命中不一定都是乱码，但发布前必须人工确认。

本项目常见中文文件 ​

  • README.md
  • docs/*.md
  • index.html
  • js/**/*.js
  • css/**/*.css
  • service-worker.js

这些文件出现乱码会直接影响应用界面、离线缓存和打包产物。