怎么使用Node.js命令行批量格式化项目中的JS文件

在日常 JavaScript 开发中，随着代码量增长和多人协作，不同成员的代码缩进、分号习惯和引号格式往往各不相同。手动逐个打开文件调整不仅效率低下，还极易遗漏。在 Node.js 环境下，最标准且高效的批量格式化方式是借助命令行工具直接对整个项目目录执行递归扫描与重写。本文将介绍如何使用主流的 Prettier 命令行工具一键格式化所有 JS 文件，如何配置规则与忽略文件，以及在特殊需求下如何编写纯 Node.js 脚本实现批量格式化。

一、使用 Prettier 命令行快速批量格式化

Prettier 是目前前端和 Node.js 生态中使用最广泛的代码格式化工具。它专注于解析代码语法树并重新输出整洁的代码，且提供了功能完善的命令行接口（CLI）。使用 Prettier 批量格式化无需在编辑器中频繁触发保存，只需在终端敲入一条命令。

1. 免安装直接执行（npx）

在已经安装了 Node.js（建议 Node.js 14 及以上版本）的环境下，打开系统终端并进入你的项目根目录，直接执行以下命令：

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

该命令中各组成部分的含义如下：

• npx：Node.js 自带的包执行器，会自动下载并运行最新版 Prettier，无需事先全局安装。
• --write：指示工具直接将格式化后的结果覆写回原文件。如果不加该参数，Prettier 只会将格式化后的文本打印到终端标准输出，而不会修改磁盘文件。
• "**/*.js"：Glob 通配符表达式，表示递归匹配当前目录及其所有子目录下的所有 .js 文件。请务必用双引号将通配符包裹起来，防止操作系统的 Shell 提前将其展开为局部文件名列表。

2. 预先检查而非直接修改（--check）

如果你在提交代码或在持续集成（CI）服务器上只想验证项目代码是否符合格式要求，而不想直接写入文件，可以使用 --check 参数：

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

执行后终端会逐个列出不合规的文件名。若存在未格式化的文件，命令退出码为非 0，非常适合用作自动化质量门禁。

二、配置团队统一的格式化规则与忽略清单

如果直接运行默认命令，Prettier 会使用其内置的默认配置进行排版。为了让团队所有人格式化出的代码完全一致，必须在项目根目录中维护专属配置文件。

1. 创建规则文件 .prettierrc

在项目根目录新建名为 .prettierrc 或 .prettierrc.json 的文件，写入适合团队的 JSON 格式规则：

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80,
  "arrowParens": "avoid"
}

配置项解释：

• semi: 语句末尾是否添加分号，true 表示必须保留分号。
• singleQuote: 是否使用单引号代替双引号。
• tabWidth: 每个缩进层级的空格数量。
• trailingComma: 多行对象或数组末尾是否添加逗号，"es5" 会在有效的地方自动补全逗号。
• printWidth: 每行代码的最大字符数，超出则自动折行排版。

2. 创建忽略文件 .prettierignore

在项目根目录执行批量格式化时，绝不能去格式化 node_modules 下的第三方依赖，也不应修改打包产物或压缩文件。新建 .prettierignore 文件：

node_modules
dist
build
coverage
*.min.js

Prettier 在启动时会自动读取此文件，将列出的文件夹与文件排除在扫描列表之外，从而避免无效的大量磁盘 I/O 和第三方源码污染。

三、将批量格式化固化为 npm 脚本

为了让项目维护更加工程化，避免团队成员每次手动输入较长的参数，建议将 Prettier 安装为项目的开发依赖，并在 package.json 中定义统一的快捷命令。

1. 本地安装依赖

npm install --save-dev prettier

本地安装能锁定 Prettier 的版本号，确保不同电脑执行时格式化结果完全一致，不会因为 npx 拉取了更新的版本而导致非预期的代码格式变化。

2. 在 package.json 中配置 scripts

打开 package.json，在 "scripts" 字段中增加 format 与 format:check 命令：

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "format": "prettier --write \"src/**/*.js\" \"test/**/*.js\"",
    "format:check": "prettier --check \"src/**/*.js\""
  },
  "devDependencies": {
    "prettier": "^3.2.5"
  }
}

3. 命令行调用

配置完成后，在项目根目录运行以下命令即可实现一键批量格式化：

npm run format

这会按照 package.json 中指定的目录范围自动检索文件并按规则写盘，既直观又不易出错。

四、使用纯 Node.js 脚本实现自定义批量格式化

在某些特殊业务场景下，单纯调用现有 CLI 可能无法满足要求。例如：你可能需要在格式化文件的同时替换版权信息头、检测敏感注释、或者根据特定规则动态跳过某些文件。此时可以利用 Node.js 提供的文件系统 API（fs）与 Prettier 的 Node.js 编程接口，编写一段专用的格式化脚本。

1. 编写 format-all.js 脚本

在项目根目录创建 scripts/format-all.js：

const fs = require('fs');
const path = require('path');
const prettier = require('prettier');

// 需要扫描的根目录
const TARGET_DIR = path.resolve(__dirname, '../src');

// 递归遍历指定目录下所有的 .js 文件
function getJsFiles(dir, fileList = []) {
  const files = fs.readdirSync(dir, { withFileTypes: true });
  for (const file of files) {
    const fullPath = path.join(dir, file.name);
    if (file.isDirectory()) {
      if (file.name !== 'node_modules' && file.name !== 'dist') {
        getJsFiles(fullPath, fileList);
      }
    } else if (file.isFile() && file.name.endsWith('.js')) {
      fileList.push(fullPath);
    }
  }
  return fileList;
}

async function run() {
  const files = getJsFiles(TARGET_DIR);
  console.log(`找到 ${files.length} 个 JS 文件，准备执行批量格式化...`);

  // 加载项目根目录的 .prettierrc 配置
  const options = (await prettier.resolveConfig(TARGET_DIR)) || {};
  options.parser = 'babel';

  let updatedCount = 0;
  for (const filePath of files) {
    const rawCode = fs.readFileSync(filePath, 'utf-8');
    const formatted = await prettier.format(rawCode, {
      ...options,
      filepath: filePath
    });

    if (formatted !== rawCode) {
      fs.writeFileSync(filePath, formatted, 'utf-8');
      console.log(`[已更新] ${path.relative(process.cwd(), filePath)}`);
      updatedCount++;
    }
  }

  console.log(`批量处理完毕！共修改 ${updatedCount} / ${files.length} 个文件。`);
}

run().catch(err => {
  console.error('格式化失败:', err);
  process.exit(1);
});

2. 在命令行执行该脚本

打开终端直接使用 node 命令运行该脚本：

node scripts/format-all.js

该脚本展示了纯 Node.js 操作文件的基本逻辑：通过递归同步遍历读取文件列表，利用 Prettier API 转换代码字符串，判断前后差异后再覆写回磁盘。这种方式赋予了开发者完全的掌控力。

五、常见问题排查与注意事项

1. Glob 通配符在 Windows 与 Mac/Linux 上的引号差异

在 macOS 或 Linux 系统的 zsh / bash 中，如果命令行不加双引号，例如直接运行 npx prettier --write **/*.js，Shell 会在命令传递给 Prettier 之前自动展开路径。如果当前项目子文件夹层级过深，可能会导致参数过长报错或只格式化了当前第一层目录。因此，在任何操作系统中，始终使用双引号将路径表达式包裹起来是最佳实践。

2. 与 ESLint 规则冲突的处理

如果项目同时使用了 ESLint 进行代码质量审查，可能会遇到 Prettier 格式化后的代码触发 ESLint 报错（例如分号、空格或引号规则分歧）。解决这一冲突的标准方案是安装 eslint-config-prettier：

npm install --save-dev eslint-config-prettier

并在 .eslintrc.json 的 extends 数组最末尾添加 "prettier"，这样 ESLint 就会自动关闭所有可能与 Prettier 冲突的排版规则，让 ESLint 专注语法与逻辑质量，Prettier 专注代码格式。

六、总结

使用 Node.js 命令行批量格式化项目中的 JS 文件，核心路径可以总结为以下几步：

1. 开箱即用：使用 npx prettier --write "**/*.js" 可以立即对全量 JavaScript 代码进行批量格式化与落盘。
2. 规则固化：在项目根目录添加 .prettierrc 与 .prettierignore，规范缩进、引号等细节，并隔离 node_modules 等非业务文件。
3. 工程化脚本：将执行语句配置进 package.json 的 scripts，通过 npm run format 统一团队执行体验。
4. 灵活定制：遇到非标准文件读写或定制批处理需求时，可调用 Node.js 原生 fs 模块与 Prettier API 编写专用 Node 脚本。

掌握这套方法后，无论面对刚接手的遗留项目还是多人持续迭代的复杂代码库，都能在数秒内让全部 JavaScript 源码恢复清爽、规范的排版。