JavaScript 格式化

JavaScript 格式化所做的事情，是把一段写得很赶、从压缩产物里抠出来或从堆栈信息里拷过来的代码，重新整理成缩进一致、断行清晰、括号对齐的形状。脚本本身的行为完全不会改变，但它从“看不下去”变成了“可以读”。这件事情看似只是排版调整，却直接决定了代码评审、调试和交接的效率。

为什么格式化值得作为独立动作，而不是写代码的副产物

线上 JavaScript 出问题，大多数不是算法本身，而是结构上的：少了一个花括号、回调嵌套深了一层、箭头函数比预期早一步返回了 `undefined`。这些问题在一行流的代码里几乎看不出来，一旦被正确缩进就会立刻显形。因此格式化更适合作为一个独立动作，而不是“写代码时顺手”的副产物——它能保证不同人读到的，都是同一份结构清晰的版本。

一个合理的格式化器会改什么、不会动什么

格式化可以调整的，是文件的视觉形状：缩进层级、换行位置、花括号摆放、链式调用的折行方式。格式化不能改变的，是标识符拼写、语句的先后顺序、字符串/正则/模板字符串里的内容，也不能用增减分号的方式悄悄改变 ASI（自动分号插入）的行为。

• 块级结构按统一缩进展开，所用字符（空格或制表符）和深度与项目其它文件一致。
• 每条语句独占一行：一个字符的逻辑变更对应一行 diff，审查时不会被排版噪声干扰。
• 长链式调用按 `.` 折行展开，让调用链像树一样可视化，阅读时无需手工拆解。
• 注释位置全部保留：注释是代码评审记录的一部分，不是可有可无的装饰。
• 声明顺序、表达式顺序、显式分号位置都与源代码完全等价，不做任何隐式重排。

一句话原则：格式化前后，解析出来的 AST 应当完全相同。任何会改变 AST 的动作，都已经越过了“格式化”的边界，进入了“重构”的范畴。

如何使用这个工具

1. 先在 JavaScript 格式化 中准备一份有代表性的需要更适合阅读审查的 JavaScript 片段和复制代码，不要一开始就处理最大或最敏感的真实内容。
2. 执行处理流程并生成更便于对比、批注和检查的格式化 JavaScript 结果后，优先检查字符串、注释、分号边界、正则字面量、嵌套代码块，以及结果是否仍符合预期运行行为，再判断结果是否真的可用。
3. 只有当结果已经适合用于代码审查、调试、文档示例和支持排查，并且不再触发这条风险提醒时，才复制或下载输出：格式化只是可读性步骤，不能替代 lint 检查或真实运行时验证。

JavaScript 格式化 示例

这个 JavaScript 格式化 示例使用有代表性的需要更适合阅读审查的 JavaScript 片段和复制代码，展示生成后的更便于对比、批注和检查的格式化 JavaScript 结果，便于你先确认字符串、注释、分号边界、正则字面量、嵌套代码块，以及结果是否仍符合预期运行行为，再把同样设置用于真实输入。

示例输入

function add(a, b) { return a + b; }

预期输出

function add(a,b){return a+b}

把压缩或随手写的片段重新格式化

// 格式化前：从打包产物里复制出来
function loadUsers(ids){return Promise.all(ids.map(id=>fetch("/api/users/"+id).then(r=>r.json())))}

// 格式化后：适合审查和做 diff
function loadUsers(ids) {
  return Promise.all(
    ids.map((id) =>
      fetch("/api/users/" + id).then((r) => r.json())
    )
  );
}

格式化 JavaScript 最能省时间的场景

“格式化值不值得做”，关键看这段代码会不会被多人、多次阅读。下面这些场景里，先格式化再阅读几乎一定划算。

• 线上报错指向压缩产物，拿到原始片段或 source map 还原后的代码后，先格式化再读。
• 评审第三方片段、Gist 或社区示例：先格式化，再决定是否合入项目。
• 整理从聊天、工单里复制来的代码：传输过程往往把空白吃掉了一半，需要先恢复结构。
• 新人 onboarding：格式化后的文件让每个读者都从同样的视觉结构开始，避免编辑器差异引起的认知偏差。
• 撰写文档、博客或幻灯片：示例代码必须排版整齐，否则读者根本顺不下来。

格式化无法告诉你的事情

格式化让代码变得可读，但“可读”并不等于“正确”。下面这些问题，无论缩进多漂亮都不会自动消失，需要 Lint、类型检查或真实执行来发现。

• 逻辑 bug：循环边界差一、条件分支写反，格式化前后都同样工整。要靠测试，而不是排版。
• 纯 JavaScript 里的类型不匹配：格式化器看不到类型信息，字符串和数字的隐式转换不会被它发现，要交给 TypeScript 或 JSDoc 加 Lint。
• 异步陷阱：少写一个 `await`、Promise 拒绝没人处理、后台任务被无声忽略——这些缩进展示不出来，需要专门的 Lint 规则与 runtime 检测。
• 性能问题：嵌套循环再清晰也还是 O(n²)。格式化让结构可见，但不会让运行更快，需要 profile 和压测来定位。

格式化器与容易混淆的工具的对照

使用注意

• 复用更便于对比、批注和检查的格式化 JavaScript 结果前，先检查字符串、注释、分号边界、正则字面量、嵌套代码块，以及结果是否仍符合预期运行行为。
• 格式化只是可读性步骤，不能替代 lint 检查或真实运行时验证。
• 当结果会影响生产工作或客户可见内容时，应保留原始需要更适合阅读审查的 JavaScript 片段和复制代码以便回退和核对。

JavaScript 格式化 参考说明

JavaScript 格式化 的参考说明应始终围绕需要更适合阅读审查的 JavaScript 片段和复制代码、生成的更便于对比、批注和检查的格式化 JavaScript 结果，以及用于代码审查、调试、文档示例和支持排查前必须确认的检查点。

• 输入重点：需要更适合阅读审查的 JavaScript 片段和复制代码。
• 输出重点：更便于对比、批注和检查的格式化 JavaScript 结果。
• 复核重点：字符串、注释、分号边界、正则字面量、嵌套代码块，以及结果是否仍符合预期运行行为。

参考资料

• ECMAScript Language Specification
• MDN: JavaScript reference