← 返回目录 > ← 返回总览

JSON语言检查工具选型与落地建议

1. 工具选型表

工具	简介	优先级	误报率	告警抑制（屏蔽）方式	适用场景
check-json（pre-commit-hooks 内置）	语法检查：pre-commit-hooks 内置	必选	无	—	本地增量、PR增量、PR全量
Gitleaks	密钥检测：正则+熵分析，递归解码	必选	低	行级注释、工具配置	本地增量、PR增量、PR全量、主干全量、定时全量
pre-commit	调度框架：声明式 YAML，依赖隔离	推荐	无	工具配置	本地增量、PR全量
Prettier	格式化：AST 引擎，20+ 语言	推荐	无	行级注释、块级注释、文件级注释、工具配置	本地增量、本地全量、PR增量、PR全量
Codespell	拼写检查：Wikipedia 常见错误字典	推荐	低	行级注释、工具配置	本地增量、PR增量、PR全量

2. 主流社区参考

2.1 VS Code

VS Code 展示了超大型项目如何管理复杂 ESLint 配置（117KB）——通过 .eslint-plugin-local 目录封装项目专属规则，.eslint-allowed-javascript-files 白名单渐进式迁移历史代码。对 JSON Schema 的编辑器支持是 VS Code 内置能力。

• 仓库地址：https://github.com/microsoft/vscode （⭐ 187.7k）
• 使用工具：ESLint（flat config，117894 字节超大型配置）、CodeQL（安全分析）、EditorConfig、tsfmt（TypeScript 格式化）、LSIF（代码索引）
• 工作流：通过 Gulp 组织构建；ESLint flat config 管理庞大的规则集；CodeQL 做安全扫描；.eslint-allowed-javascript-files 白名单管理历史 JS 文件
• 关键配置：eslint.config.js（117894 字节）、.eslint-ignore、.eslint-allowed-javascript-files、.eslint-plugin-local/（自定义插件目录）、tsfmt.json、CodeQL.yml
• 借鉴价值：超大型项目通过自定义插件目录封装项目专属规则；白名单机制渐进式迁移历史代码；JSON Schema 的编辑器支持是 VS Code 内置能力，无需额外配置

2.2 SchemaStore

SchemaStore 是 JSON Schema 生态的核心，其 .pre-commit-config.yaml 是“schema 项目”pre-commit 配置的优秀参考。该项目本身就是 JSON Schema 仓库，每个 schema 文件即是被验证对象。

• 仓库地址：https://github.com/SchemaStore/schemastore （⭐ 3.8k）
• 使用工具：pre-commit 框架、Prettier（格式化 JSON）、ESLint、EditorConfig、JSON Schema 自验证
• 工作流：使用 pre-commit 统一管理本地与 CI 检查；Prettier 格式化 JSON；ESLint 检查辅助 JS 脚本；该项目本身就是 JSON Schema 仓库，每个 schema 文件即是被验证对象
• 关键配置：.pre-commit-config.yaml、.prettierrc.cjs、eslint.config.js、jsconfig.json、CONTRIBUTING.md（32916 字节，详细贡献规范）
• 借鉴价值：对维护大量 JSON 配置文件的项目，Prettier + JSON Schema 自验证是基本组合；SchemaStore 的 .pre-commit-config.yaml 是 schema 项目的优秀参考

2.3 npm CLI

npm CLI 展示了包管理器项目的特殊关注点：.licensee.json 许可证合规检查对分发到生产环境的关键工具必备；release-please 实现语义化版本自动化发布；.eslintrc.local.js 机制允许本地个性化规则覆盖。

• 仓库地址：https://github.com/npm/cli （⭐ 10.0k）
• 使用工具：ESLint、commitlint、licensee（许可证合规检查）、release-please（自动化发布）、EditorConfig
• 工作流：通过 workspaces 管理 monorepo；ESLint 检查代码；commitlint 约束提交信息；.licensee.json 做许可证白名单检查
• 关键配置：.eslintrc.js、.eslintrc.local.js（本地覆盖）、.commitlintrc.js、.licensee.json、release-please-config.json
• 借鉴价值：对分发到生产环境的工具，许可证合规检查（.licensee.json）必备；.eslintrc.local.js 机制允许本地个性化规则覆盖；release-please 实现语义化版本自动化发布

2.4 TypeScript 编译器

TypeScript 编译器项目本身使用 dprint 替代 Prettier，体现 dprint 在多语言（TS/JS/Markdown/TOML）统一格式化上的优势。Knip 用于大型项目检测未使用导出，对类型库项目很有价值。

• 仓库地址：https://github.com/microsoft/TypeScript （⭐ 109.9k）
• 使用工具：dprint（多语言 formatter）、ESLint、c8（覆盖率）、Hereby（构建）、Knip（未使用代码检测）
• 工作流：通过 Herebyfile 组织构建任务；dprint 统一格式化多种语言；Azure Pipelines 做 CI；Knip 检测未使用的导出
• 关键配置：.dprint.jsonc、eslint.config.mjs、.c8rc.json、knip.jsonc、Herebyfile.mjs
• 借鉴价值：dprint 在多语言统一格式化上优于 Prettier；Knip 检测死代码对类型库项目很有价值；tsconfig.json 的 schema 验证由 VS Code 内置 SchemaStore 集成完成

2.5 OpenAPI-Specification

OpenAPI-Specification 展示了规范文档项目的检查方案：双 markdownlint 配置（通用 + 规范专属）；linkspector 对维护大量交叉引用的文档项目必备；Vitest 用于验证 JSON Schema 本身的正确性。

• 仓库地址：https://github.com/OAI/OpenAPI-Specification （⭐ 31.1k）
• 使用工具：markdownlint、linkspector（链接检查）、Vitest（测试）、EditorConfig
• 工作流：通过 GitHub Actions 运行 markdownlint 和 linkspector；Vitest 运行 JSON Schema 验证测试；维护两套 markdownlint 配置
• 关键配置：.markdownlint.yaml（通用）、spec.markdownlint.yaml（规范文档专属）、.linkspector.yml、vitest.config.mjs、style-guide.md
• 借鉴价值：双 markdownlint 配置可针对不同类型文档放宽/收紧规则；linkspector 对维护大量交叉引用的文档项目必备；Vitest 用于验证 JSON Schema 本身的正确性

3. 工程配置建议

JSON 配置项目以 check-json 基础语法检查 + Prettier 格式化为核心组合，配合 pre-commit 统一调度密钥检测和拼写检查，是 SchemaStore 等主流 JSON Schema 项目的通用做法。

3.1 工程配置文件汇总

配置文件	配置内容/作用	使用场景	维护建议
.prettierrc / .prettierignore	JSON 格式和排除路径	格式化检查	lockfile、生成 JSON 排除
.pre-commit-config.yaml	官方基础 hook、密钥检测、拼写检查、Prettier 格式化	本地提交前、PR 轻量门禁	由仓库统一维护版本；新增 hook 应说明耗时和误报处理方式
.codespellrc	拼写词典	拼写检查	产品名、缩写、人名、领域术语
.gitignore / 工具 ignore 文件	排除构建产物、依赖目录、生成代码、第三方代码	本地、PR、全量检查	生成代码和 vendored 目录优先在 ignore 文件中集中排除
.github/workflows/*	PR 门禁、主干全量、夜间任务	PR、主干、发布前、夜间	CI 命令应尽量复用本地命令，避免本地和 CI 两套规则漂移

3.2 .pre-commit-config.yaml

官方基础 hook 中的 check-json 负责基础语法，通用安全和拼写检查覆盖全仓，Prettier 通过 repo: local 调用项目的 Node.js 依赖负责 JSON 格式化。JSON Schema、OpenAPI Schema 或业务配置 Schema 校验不属于 pre-commit 官方最小配置，应按项目需要单独配置。

说明：pre-commit/mirrors-prettier 仓库已归档（最新镜像版本为 v4.0.0-alpha.8，对应 Prettier 4.0.0-alpha），不再跟进 Prettier 最新稳定版。因此推荐通过 repo: local 调用项目已安装的 Prettier，以使用最新稳定版本。

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace # 移除行尾空白字符
      - id: end-of-file-fixer # 确保文件以换行符结尾
      - id: check-yaml # 校验 YAML 文件语法
      - id: check-json # 校验 JSON 文件语法
      - id: check-xml # 校验 XML 文件语法
      - id: check-merge-conflict # 检查未解决的合并冲突标记
      - id: check-added-large-files # 拦截超大文件提交（默认 500KB）
      #  args: ["--maxkb", "500"]      # 支持自定义修改
      - id: detect-private-key # 检测私钥/敏感信息泄露
  # ===== 以下为可选工具，按需启用 =====
  # - repo: https://github.com/gitleaks/gitleaks
  #   rev: v8.24.3
  #   hooks:
  #     - id: gitleaks                  # 密钥泄露检测
  # - repo: https://github.com/codespell-project/codespell
  #   rev: v2.4.1
  #   hooks:
  #     - id: codespell                 # 拼写检查
  # ===== JSON 必选工具：默认启用 =====
  - repo: local
    hooks:
      - id: prettier-json # 格式化（修复模式）
        name: prettier json
        entry: npx prettier --check --ignore-unknown
        language: system
        types: [json]

如果项目有 tsconfig.json、OpenAPI、业务配置或 API Schema，应在 PR 门禁中单独执行 Schema 校验；大型 lockfile 或生成 JSON 可通过 .prettierignore 或 hook exclude 排除。

4. 本地开发检查场景

check-json、Prettier、Gitleaks 和 Codespell 已由 pre-commit 组合配置覆盖，本地默认检查不需要再单独运行原生命令。tsconfig.json、OpenAPI、业务配置和 schema 文件还需要专用校验。大型 lockfile 和生成 JSON 通常不适合格式化，应在 .prettierignore 或 hook exclude 中排除。

npm install --save-dev prettier
python -m pip install pre-commit
pre-commit install
pre-commit run --all-files

5. PR 门禁检查场景

JSON PR 门禁建议对变更文件增量执行 check-json 和 Prettier。主干全量检查所有手写 JSON；大型 lockfile 或生成 JSON 可在 .prettierignore 中排除。JSON 语法错误、格式漂移、schema 不匹配和密钥泄露都应阻断合入。

name: JSON Quality
on: [pull_request, push]
jobs:
  json:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: npm install -g prettier
      - run: pip install pre-commit
      - run: pre-commit run --all-files

6. 告警抑制

工具	优先做法	局部屏蔽
Prettier	用 .prettierignore 排除生成 JSON 和 lockfile	Prettier 告警抑制
pre-commit	用 exclude 排除非标准 JSON 模板	pre-commit 配置
Gitleaks	用 allowlist 或 .gitleaksignore 管理确认过的假阳性	Gitleaks 告警抑制
Codespell	在 .codespellrc 中维护忽略词	Codespell 告警抑制

误报处理遵循"先修正、再收敛规则、最后局部屏蔽"的顺序。能通过代码改写解决的告警不建议直接屏蔽；确实属于工具误报或历史兼容问题时，优先使用集中配置排除规则。生成代码和第三方代码应在工具配置中排除目录。

7. 落地步骤

1. 先提交 .pre-commit-config.yaml、.prettierrc、.codespellrc 和 CI 工作流，不立即阻断历史问题。
2. 对新项目直接开启严格规则；对存量项目先只检查变更文件或建立 baseline。
3. 在 README 或贡献指南中写清本地命令、PR 门禁命令和误报屏蔽要求。
4. 将 Prettier 设置为自动修复（编辑器保存时触发），安全扫描默认不自动改代码。
5. 每次规则升级单独发 PR，避免与业务改动混在一起。
6. 每季度清理一次 baseline、忽略列表和长期存在的屏蔽注释。

← 返回目录 > ← 返回总览