js代码格式化源码：从原理到实现的完整教程

准备工作：理解格式化器的基本组成

在动手写代码之前，先明确一个格式化器需要完成哪些任务。它通常包含三个部分：词法分析、语法分析和代码生成。词法分析把源码字符串切分成有意义的记号，比如关键字、标识符、运算符和标点；语法分析把这些记号组织成树形结构，反映代码的嵌套关系；代码生成则按照预设的缩进、换行和空格规则，把树重新输出为字符串。

你不需要手写完整的解析器，可以借助成熟的解析库（如Acorn或Esprima）得到抽象语法树（AST），把精力集中在规则设计和输出逻辑上。准备一个空目录，初始化项目，安装解析库，再准备几段风格混乱的测试代码，覆盖函数声明、对象字面量、条件语句和链式调用等常见结构。

分步操作：从解析到输出的实现路径

第一步：读取源码并生成AST。 调用解析库的parse方法，传入源码字符串和选项，得到AST对象。注意处理解析错误，遇到语法不合法时给出明确提示，而不是让程序崩溃。

第二步：遍历AST并收集节点信息。 使用递归或访问者模式遍历每个节点，记录节点的类型、起始位置、结束位置以及父子关系。这一步不修改树，只是为后续输出做准备。

第三步：设计格式化规则。 规则决定输出风格，例如：缩进用几个空格、运算符两侧是否留空格、对象属性是否换行、函数参数过多时如何折行。把规则写成配置对象，方便后续调整。

第四步：基于AST生成代码。 从根节点开始递归输出，根据节点类型拼接字符串。遇到块语句时增加缩进层级，遇到二元表达式时在运算符两侧插入空格，遇到逗号分隔的列表时决定是否换行。注意保留原始注释，注释通常不在AST节点中，需要单独从源码中提取并关联到相邻节点。

第五步：对比输出与预期。 用准备好的测试代码运行格式化器，逐段检查输出结果，修正规则中的遗漏。可以编写简单的断言脚本，自动比较格式化前后的语义是否一致。

常见错误与排查

• 丢失注释：多数解析库默认不把注释放进AST，需要开启注释收集选项，或在词法阶段单独记录注释位置，再在输出时按位置插入。
• 缩进层级错乱：检查递归输出时是否在进入块级节点前增加层级、离开后恢复层级。常见错误是只在部分节点类型上处理缩进，导致嵌套结构混乱。
• 字符串或模板字面量被改写：格式化器不应改变字符串内容。如果输出结果中字符串被转义或拼接，说明在生成阶段错误地处理了字面量节点。
• 运算符优先级被破坏：当你在表达式两侧添加空格或换行时，要确保不会引入歧义。例如在return语句后换行可能导致返回undefined，需要特别处理。
• 解析失败：如果源码包含较新的语法特性，旧版解析库可能不支持。升级解析库版本，或配置对应的语法插件。

进阶技巧：让格式化器更实用

当基础版本跑通后，可以从几个方向继续完善。支持配置文件：允许用户通过配置文件覆盖默认规则，例如缩进宽度、引号风格、分号取舍。读取配置后合并到规则对象中，再传给生成阶段。

处理长行折行：对于超过一定宽度的行，按规则在合适的位置换行。可以在生成阶段维护当前列号，遇到超宽时在逗号、运算符或参数列表处插入换行和缩进。

保留空行：原始代码中的空行对可读性有帮助，可以在遍历时记录空行位置，输出时在对应节点之间保留一个空行。

与编辑器集成：把格式化器封装成函数，接收源码字符串返回格式化后的字符串。这样就能在编辑器的保存钩子中调用，或作为命令行工具使用。

编写测试用例：为每种节点类型准备输入和期望输出，用测试框架自动运行。当规则调整时，测试能快速发现回归问题。

常见问题