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