js代码格式化使用教程：新手完成第一张作品的方法

刚开始写 JavaScript，代码能运行就已经不容易；写着写着，缩进不一、空格忽多忽少、长表达式挤在一行里，又会让代码越来越难读。代码格式化工具可以自动统一这些外观细节，让你把注意力放在程序做什么，而不是每行空几格。

这篇教程会用 Prettier 格式化 JavaScript，并从零做一个可以点击加减的计数器页面。跟着完成后，你会得到一份能在浏览器里运行的小作品，也会了解格式化工具做不到什么、哪些场景需要谨慎处理。

一、JavaScript 代码格式化是什么

代码格式化是按照一套排版规则，调整代码的缩进、空格、换行和引号等外观。例如，工具可以把挤在一行里的函数整理成多行，也可以统一对象属性的排布。

格式化通常不改变程序的预期逻辑。不过，它并不等于代码检查，也不等于代码修复：拼写错误、错误的业务判断、危险的输入处理，不会因为排版整齐就自动消失。格式化之后仍要运行和检查程序。

适合使用格式化的场景

• 刚开始学习：用固定排版习惯减少视觉混乱，更容易看出括号、代码块和嵌套结构。
• 维护已有项目：在遵守项目规则的前提下统一代码风格，避免不同文件各写各的。
• 提交代码前：先格式化变更文件，让代码评审关注逻辑，而不是空格差异。
• 团队协作：把格式规则写进配置和自动化流程，降低个人习惯带来的差异。

不适合盲目格式化的场景

• 项目已有明确的格式化工具或规则时，不要另装一套相冲突的规则。
• 来源不明或可能含有恶意内容的代码，不要为了“看清楚”就直接执行；格式化不是安全扫描。
• 对外部库的压缩文件、生成文件或大型历史文件，不要未经确认就整文件格式化，可能造成无关的大量改动。
• 代码本身无法解析时，格式化工具可能报错，也可能无法按预期处理；应先看错误位置和文件类型。

二、准备工具：安装 Prettier

Prettier 是常见的代码格式化工具，支持 JavaScript，也支持多种其他语言和文件格式。这里将它安装在项目本地，避免依赖机器上不确定的全局版本。开始前需要安装 Node.js；可以在终端运行 node -v 和 npm -v 检查是否可用。

创建一个空文件夹，例如 js-first-work，在该文件夹中打开终端，执行：

npm init -y
npm install --save-dev prettier

npm init -y 会创建默认的 package.json；第二条命令会把 Prettier 安装为当前项目的开发依赖。安装后，项目通常会多出 node_modules 和 package-lock.json。前者一般不提交到版本控制，后者通常应与项目一同保留，以便记录依赖版本。

三、写一份故意不整齐的 JavaScript

在项目中新建 counter.js，粘贴下面代码。它能正常表达一个计数器的逻辑，但缩进和换行比较随意：

const counter={value:0,
 add:function(step){this.value=this.value+step;return this.value},
 reset:function(){this.value=0;return this.value}};

function showMessage(name,count){
  const text=name+" 当前数量："+count
 console.log(text);return text
}

showMessage("计数器",counter.add(1));

先不用急着手工整理。我们先让工具按照统一规则排版，然后再逐部分理解它。

四、第一次格式化：命令行操作

在项目终端中执行：

npx prettier counter.js --write

npx 会运行项目中安装的命令；--write 表示把格式化结果写回文件。运行后，counter.js 会变成类似下面的样子：

const counter = {
  value: 0,
  add: function (step) {
    this.value = this.value + step;
    return this.value;
  },
  reset: function () {
    this.value = 0;
    return this.value;
  },
};

function showMessage(name, count) {
  const text = name + " 当前数量：" + count;
  console.log(text);
  return text;
}

showMessage("计数器", counter.add(1));

具体结果会受到 Prettier 版本和项目配置影响；上面的结果展示的是一种常见排版。格式化工具重新安排了空格、缩进和换行，并按当前规则处理分号、尾随逗号等细节。它没有替你判断 counter.add(1) 是否符合产品需求，也没有改变计数器的设计。

命令行还有一种只检查、不写入文件的用法：

npx prettier counter.js --check

如果文件已经符合当前规则，命令会报告通过；如果不符合，会指出文件需要格式化。--check 适合放在检查流程里，避免检查时直接改动文件。

五、添加基础配置并格式化整个项目

团队项目最好把关键规则放进配置文件，保证不同人运行格式化时使用一致的设置。在项目根目录创建 .prettierrc.json：

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all"
}

• semi：是否在适用的语句末尾添加分号。
• singleQuote：是否优先使用单引号。需要注意，JavaScript 字符串中若包含单引号，仍可能用转义或其他引号表示。
• tabWidth：缩进宽度；这里设置为两个空格。
• trailingComma：控制对象、数组等结构中的尾随逗号策略。

这里给的是一组可用的示例，不是所有项目都必须采用的标准。若现有项目已经有 Prettier 配置、编辑器规则或团队约定，应优先遵循项目要求，不要为了套用示例覆盖原有规则。

保存配置后重新格式化文件：

npx prettier counter.js --write

也可以格式化项目内匹配的 JavaScript 文件：

npx prettier "**/*.js" --write

这条命令会处理当前目录及子目录中匹配到的 .js 文件。使用通配符前先确认范围，尤其要避免把依赖目录、构建产物或生成文件纳入格式化。不同终端对引号和通配符的处理可能不同；如果命令没有匹配到文件，可先尝试指定单个文件，或检查所在目录。

六、制作第一个作品：浏览器计数器

现在把例子做成一个网页。新建 index.html，将下面内容原样保存。这个页面包含计数显示、增加、减少和重置按钮，JavaScript 通过事件监听器更新数字。

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>我的计数器</title>
    <style>
      body {
        max-width: 36rem;
        margin: 4rem auto;
        padding: 0 1rem;
        font-family: sans-serif;
        text-align: center;
      }

      #count {
        font-size: 3rem;
      }

      button {
        margin: 0.25rem;
        padding: 0.6rem 1rem;
        font-size: 1rem;
        cursor: pointer;
      }
    </style>
  </head>
  <body>
    <main>
      <h1>我的计数器</h1>
      <p id="count" aria-live="polite">0</p>
      <button id="decrease" type="button">减一</button>
      <button id="increase" type="button">加一</button>
      <button id="reset" type="button">重置</button>
    </main>

    <script>
      const countElement = document.querySelector("#count");
      const decreaseButton = document.querySelector("#decrease");
      const increaseButton = document.querySelector("#increase");
      const resetButton = document.querySelector("#reset");

      let count = 0;

      function renderCount() {
        countElement.textContent = String(count);
      }

      decreaseButton.addEventListener("click", function () {
        count -= 1;
        renderCount();
      });

      increaseButton.addEventListener("click", function () {
        count += 1;
        renderCount();
      });

      resetButton.addEventListener("click", function () {
        count = 0;
        renderCount();
      });
    </script>
  </body>
</html>

双击 index.html，或在浏览器中打开它，就可以点击按钮。这个小页面不需要安装框架，也不需要启动服务器。它适合用来认识 HTML、CSS 和 JavaScript 如何协作，但不代表所有项目都能直接用双击文件的方式运行；一些模块、网络请求或浏览器功能可能需要本地开发服务器。

格式化 HTML 文件中的脚本

上一节安装的 Prettier 可以处理 HTML 文件，包括其中的脚本格式。执行：

npx prettier index.html --write

Prettier 会根据文件类型解析内容并尝试格式化。保存后重新打开页面，功能应保持相同。如果页面突然报错，不要假设格式化一定是原因，也不要因为工具运行成功就认定代码没有问题；打开浏览器开发者工具的控制台，查看报错文件和行号，再检查相关代码。

七、把常用命令写进 package.json

每次手动输入命令不方便时，可以在 package.json 的 scripts 中添加脚本。保留原有内容，只在 scripts 对象里增加以下两项即可：

{
  "scripts": {
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

这是局部片段，不要把它当成完整的 package.json 覆盖已有文件。如果原文件已经有 scripts，应把这两条键值加入原对象，并注意 JSON 语法要求逗号位置正确。

之后可以这样使用：

npm run format
npm run format:check

prettier . 的目标是当前项目目录下 Prettier 能识别并处理的文件，不表示项目里的每个文件都会被无差别改写。项目根目录可以添加 .prettierignore，排除构建产物等不应格式化的路径，例如：

node_modules
dist
coverage

忽略列表要按项目实际目录确定。如果团队需要格式化检查作为提交门槛，应在代码评审或持续集成流程中执行检查命令；仅仅在个人电脑里配置了脚本，并不会自动保证其他人运行过它。

八、在代码编辑器中自动格式化

也可以在常用编辑器中安装 Prettier 扩展，并将 Prettier 设为 JavaScript 和相关文件的格式化工具。不同编辑器的设置入口会变化，基本思路是：选择项目使用的 Prettier、开启保存时格式化（如果你希望自动执行），并确认编辑器没有同时启用另一套互相冲突的格式化规则。

自动保存格式化省去手动运行命令的步骤，但第一次使用时建议先明确知道格式化发生在什么时候。遇到格式突然改变，查看编辑器状态栏、扩展配置以及项目中的配置文件，确认当前到底由哪个工具和规则生效。

九、关键边界：格式化不等于检查与修复

1. 它不负责发现所有错误

格式化器需要理解文件的语法结构，才能安全地调整布局。缺少括号、字符串没有闭合等语法问题，可能使它无法解析文件。反过来，格式化成功也不意味着程序没有错误：变量取值不对、按钮逻辑写反、接口调用失败，都不属于格式化能够保证解决的问题。

排查代码时可以把步骤分开：格式化负责统一外观；浏览器控制台或运行测试负责验证行为；ESLint 等代码检查工具可以根据规则提示部分潜在问题。不同工具职责不同，不能互相替代。

2. 它不应改变业务含义，但要复查重要代码

正常情况下，格式化器会尽量保留代码的行为，只调整排版和规定范围内的语法风格。对于脚本、模板、嵌入式代码或特殊语法，应确认所用工具版本能够正确解析对应文件，并通过测试检查改动。不要把“输出看起来整齐”当作正确性的证明。

3. 格式化不会让代码变安全

格式化不是加密、杀毒、权限控制或漏洞修复工具。它不会自动阻止跨站脚本、SQL 注入、命令注入，也不会验证依赖来源。上面的计数器使用 textContent 显示数字，是因为要设置纯文本；但这并不构成对任意网页代码安全性的全面保证。处理用户输入时，仍需根据数据去向采用适当的验证、转义和安全 API。

不可信代码应先进行静态查看和风险评估，不要仅为了格式化而运行它。即使某个格式化工具通常只分析文件内容，也应使用可信来源安装工具，并了解它处理的文件和运行环境；格式化不能替代安全审查。

4. 规则可能改变文件差异

改动 singleQuote、分号或行宽等规则，可能导致大量文件出现格式差异。处理已有项目时，先查看当前配置、版本控制状态和待提交改动，再决定是否格式化。可先对单个文件试运行，确认结果后再扩大范围。

十、新手常见错误与处理方法

错误一：在错误目录执行命令

如果提示找不到文件或配置，先运行 pwd（部分 Windows 终端可用 cd 查看当前目录），确认终端位于项目根目录；再确认文件名和路径拼写正确。

错误二：没有安装项目依赖

若运行 npx prettier 提示找不到命令，可以在项目目录执行 npm install，或按前面的步骤安装 Prettier。确认终端当前目录包含 package.json。不要在每个项目里随意混用不同版本，否则格式结果可能不一致。

错误三：把检查命令当作格式化命令

--check 只检查是否符合格式，不会替你写回文件；需要实际整理文件时使用 --write。使用 --write 前也要确认目标范围，避免误改不该处理的文件。

错误四：配置文件不是有效 JSON

.prettierrc.json 必须符合 JSON 语法：属性名和字符串用双引号，键值之间用逗号分隔，最后一项后不要多写逗号。若工具提示配置解析失败，先检查括号、引号和逗号。

错误五：格式化后代码仍报错

格式化只能整理代码。若浏览器提示 Cannot read properties of null，常见原因之一是选择器没有找到页面元素；应核对 HTML 的 id 和 JavaScript 查询字符串是否一致。其他错误也应根据控制台信息检查，不要反复格式化来期待它自动修复逻辑。

错误六：每次都把整个项目重排

如果只改了一份文件，优先只格式化这份文件，控制变更范围。对已有项目运行全量格式化前，先查看版本控制状态，避免把和当前任务无关的格式变更混入提交。

十一、完成后可以这样检查

1. 确认计数器页面能打开，三个按钮分别能减少、增加和重置数字。
2. 运行 npx prettier index.html --check，确认 HTML 文件符合当前格式规则。
3. 运行 git diff（前提是项目已使用 Git），检查格式化带来的实际文件改动。
4. 若页面行为不符合预期，查看浏览器控制台并逐项排查，而不是把格式化当作调试器。

至此，你已经完成了第一份 JavaScript 小作品，并学会用命令行和配置文件整理代码。以后接手新项目时，先找到项目已有的格式规则，再决定是否安装或启用工具；写自己的练习项目时，则可以从单文件格式化开始，确认结果和行为都正常后，再逐步加入编辑器自动格式化和提交前检查。