企业官网建设流程全解析

• 前端
• CMS

导读

本文围绕 wp-calypso（WordPress.com 的 JavaScript 与 API 前端仓库）的编码规范文档 docs/coding-guidelines/trailing-whitespace.md 展开，系统讲解"所有源文件必须清除行尾尾随空白"这一基础但极易被忽视的规范：为什么必须清除、如何借助编辑器自动完成、如何在 CI/提交前用工具强制约束，以及触碰旧代码时如何用独立 commit 保证历史可读性。读完本文，你将掌握在 wp-calypso 这类大型单仓库（monorepo）中彻底消灭尾随空白的完整工作流，从编辑器配置、仓库级 .editorconfig 约束到 Prettier/ESLint 自动化，一应俱全。

一、规范原文：一句话原则与三条实操要求

trailing-whitespace.md 全文的核心原则只有一句：

All source files should have trailing whitespace removed.（所有源文件都应清除行尾尾随空白。）

在此基础上，原文档给出了三条可落地的实操要求：

1. 编辑器自动清除：Sublime Text 用户可通过设置trim_trailing_whitespace_on_save: true在保存时自动清除尾随空白。
2. 其他编辑器方案：Coda2 用户可安装 Whiteout 插件（原文档给出的插件地址）。
3. 触碰旧代码的提交纪律：当修改尚未清理尾随空白的旧代码时，先用一个独立的 commit 完成清理，再开始正式改动，这样后续改动在 Git 历史中一目了然。

这一规范并非孤立存在，它被 docs/coding-guidelines/javascript.md（"No whitespace at the end of line or on blank lines"，第 10 行）与 docs/coding-guidelines/css.md（第 296 行）等语言规范反复引用，并统一指向 trailing-whitespace.md，可见它是整个仓库代码审查中最底层的卫生基线。

二、为什么尾随空白必须清除：藏在 diff 里的噪声

尾随空白指的是每行末尾、在换行符之前残留的空格或 Tab。它肉眼几乎不可见，却在版本控制中制造真实的麻烦：

• 污染 diff：一次只改动一行代码，却因为相邻行的尾随空格被无意删掉，diff 里出现成片"无关改动"，代码审查者被迫在真实改动与空白噪声之间反复分辨。
• 干扰工具链：部分 lint 规则、构建脚本、diff 工具对行尾敏感；在 wp-calypso 的 Git 工作流（见 docs/git-workflow.md）中，干净的 diff 是 review 高效的前提。
• 破坏可追溯性：wp-calypso 大量使用git blame定位改动来源（例如排查性能回归时），尾随空白的删除与真实逻辑改动混在同一个 commit 里，会让 blame 结果失真。

这正是原文档要求"清理与改动分开提交"的根本原因：先提交纯格式清理（该 commit 内只有空白变化），再提交真实功能改动，历史中每一个 commit 的意图都保持单一、可解释。

三、编辑器层：保存即清除的自动化配置

Sublime Text（原文档方案）

按原文档指引，打开SublimeText 2 > Preferences > Settings - User（macOS 上可直接按Cmd + ,），在用户设置 JSON 中加入：

{ "trim_trailing_whitespace_on_save": true }

保存后，每次保存文件都会自动剥离所有行尾尾随空白。需注意：建议保留（或显式设为）true的还有ensure_newline_at_eof_on_save，它与 wp-calypso 的另一条规范"文件必须以换行符结尾"（见 docs/coding-guidelines/newline-at-end-of-file.md）配套，二者共同保证源文件的行级卫生。

其他主流编辑器速查

以 VS Code 为例，为 wp-calypso 配置后，settings.json可写为：

{ "files.trimTrailingWhitespace": true, "files.insertFinalNewline": true }

四、仓库层：.editorconfig 的强制基线

wp-calypso 仓库根目录的 .editorconfig 是整个项目的统一编辑器配置，它把"清除尾随空白"从个人习惯上升为仓库级约定：

root = true [*] # yes, we use tabs indent_style = tab indent_size = 4 end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true [*.md] trim_trailing_whitespace = false [*.yml] indent_size = 2 indent_style = space

结合本文主题，这份文件值得逐条解读：

• trim_trailing_whitespace = true（全局块）：所有源码文件保存时自动删除行尾空白，与 trailing-whitespace.md 的规范一一对应，是仓库级的第一道防线。
• insert_final_newline = true：保存时确保文件末尾有换行，呼应 docs/coding-guidelines/newline-at-end-of-file.md（其中还提到cat命令输出时提示符会被粘到末行、以及eol-last规则）。
• end_of_line = lf：统一行尾为 LF，配合 GitHub 上的 diff 展示与 CI 环境（Linux 服务器渲染）保持一致。
• 例外规则[*.md]下trim_trailing_whitespace = false：Markdown 文档中行尾双空格在部分 Markdown 方言里表示强制换行，因此仓库特意为.md关闭自动修剪，避免破坏有意书写的换行语义——这也是理解"规范允许例外"的典型样例。
• [*.yml]的 2 空格缩进：YAML 对缩进敏感，仓库为.yml单独规定indent_style = space与indent_size = 2。

安装 EditorConfig 插件后，VS Code、Sublime Text、JetBrains 系等主流编辑器都会在打开 wp-calypso 仓库时自动读取该文件并应用上述规则，无需每个开发者手工重复配置。

五、工具链层：Prettier 与 ESLint 的自动化兜底

编辑器与 .editorconfig 覆盖的是"本机保存时刻"，而提交前/CI 阶段的自动格式化与 lint 才是最终兜底。

Prettier：格式化即清除

wp-calypso 根目录的 .prettierrc 定义了全仓库统一的格式化规则：

useTabs: true tabWidth: 2 printWidth: 100 singleQuote: true bracketSpacing: true parenSpacing: true bracketSameLine: false semi: true trailingComma: 'es5'

Prettier 的设计哲学是"输出即规范"——prettier --write会自动删除所有行尾尾随空白、统一引号/分号/逗号风格。文档 docs/coding-guidelines/newline-at-end-of-file.md 也明确指出 Prettier "by design" 会在文件末尾补上新行。因此，在 wp-calypso 中执行格式化即可顺带完成尾随空白清理：

# 格式化全部源码（会清除尾随空白并补行尾换行） npx prettier --write "client/**/*.{js,jsx,ts,tsx}" # 仅检查而不改写，适合 CI 门禁 npx prettier --check "client/**/*.{js,jsx,ts,tsx}"

ESLint：no-trailing-spaces规则兜底

从仓库结构看，wp-calypso 通过 packages/eslint-plugin-wpcalypso（内含recommended配置，见 packages/eslint-plugin-wpcalypso/lib/configs/recommended.js）扩展 eslint-config-wpcalypso 体系。在 JavaScript/TypeScript 源文件上，ESLint 核心规则no-trailing-spaces会把"行尾存在空白"直接判为 error，从而在yarn lint或 CI 中阻止尾随空白进入主干：

# 运行仓库的 lint 检查（依赖根 package.json 中的脚本配置） yarn lint

需要特别说明的是：no-trailing-spaces与 i18n 场景并不冲突——packages/eslint-plugin-wpcalypso/docs/rules/i18n-no-collapsible-whitespace.md 约束的是翻译文案内部不可折叠的空白字符，与行尾空白属于两个完全不同的层面；前者保护用户可见文案，后者维护源码可读性。

三层防线小结

六、Git 提交纪律：先清理、后改动

原文档的最后一段是本规范中最有工程价值的一条：

When touching code that does not have trailing whitespace trimmed, make a separate commit that does the stripping before starting to make changes.

具体操作模板如下：

# 1. 先提交纯清理（该 commit 只包含尾随空白删除，不含任何逻辑变化） git add -u git commit -m "Clean trailing whitespace" # 2. 再开始并提交真正的功能改动 git commit -am "Implement feature X"

这样做的好处有三点，均可以在 wp-calypso 的日常 review 中直接验证：

1. diff 纯净：审查者看到的每个 commit 只有单一意图，功能改动不会被空白噪声淹没（对比 docs/git-workflow.md 中对小步提交、清晰历史的一贯要求）。
2. blame 准确：git blame定位到的是真实逻辑 commit，而不是混杂的"清理+改动"，排查问题时少一层干扰。
3. 回滚安全：一旦功能 commit 需要 revert，空白清理 commit 仍可保留，不会产生格式回潮。

若仓库开启了 CI lint 门禁，未清理的尾随空白会在合入前直接失败，届时"先清理后改动"不再只是建议，而是合入的硬性前提。

七、快速自查清单

在提交 wp-calypso 相关代码前，对照以下清单确认尾随空白已彻底清除：

• 编辑器已开启"保存时修剪尾随空白"（或安装了 EditorConfig 插件，读取仓库根 .editorconfig）
• 改动文件已通过npx prettier --write或编辑器格式化
• 本地yarn lint通过，无no-trailing-spaces报错
• 触碰旧代码时，"空白清理"与"功能改动"分为两个独立 commit
• 留意[*.md]例外：Markdown 行尾双空格是合法的强制换行语法，不应被自动清除

把上述任何一步固化进自己的工作流，尾随空白将不再以"隐形 diff 噪声"的形式消耗 wp-calypso 代码审查的注意力。

• 前端
• CMS