C++ 质量前置检查：clang-format 与 clang-tidy 实践指南

1. 为什么需要前置检查？

在团队协作的 C++ 项目中，代码风格不统一、潜在缺陷混入主干是常见痛点。将 clang-format 和 clang-tidy 集成到 Git 提交前（pre-commit）或 CI 流水线中，能够在代码入库前自动规范格式、发现静态问题，从而减少 Code Review 负担，提升代码库的一致性。

2. clang-format：统一代码风格

clang-format 是 LLVM 项目提供的代码格式化工具，支持 Google、LLVM、Chromium、Mozilla、WebKit 等多种预置风格，也允许通过 .clang-format 文件进行精细定制。

2.1 安装与基础使用

在 Ubuntu 上可以通过包管理器安装：

bash 复制代码

sudo apt update
sudo apt install clang-format

格式化单个文件：

bash 复制代码

clang-format -i main.cpp

其中 -i 表示原地修改。若不希望直接修改文件，可以去掉 -i，输出到标准输出进行预览。

2.2 定制 .clang-format 配置文件

在项目根目录创建 .clang-format，示例：

yaml 复制代码

BasedOnStyle: Google           # 基于 Google 风格
IndentWidth: 4                 # 缩进宽度 4 空格
ColumnLimit: 120               # 每行最大字符数
AccessModifierOffset: -4       # 访问修饰符额外缩进
AllowShortIfStatementsOnASingleLine: false
AllowShortFunctionsOnASingleLine: None
BreakBeforeBraces: Allman      # 大括号换行风格
PointerAlignment: Left         # 指针符号靠近类型

大部分选项都有清晰注释，通过官方文档可查阅完整列表。建议提交到仓库，团队成员共用同一份配置。

2.3 在 Git Pre-commit 中自动格式化

借助 pre-commit 钩子，可以在提交前自动运行 clang-format。在项目根目录创建 .pre-commit-config.yaml：

yaml 复制代码

repos:
  - repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v17.0.6
    hooks:
      - id: clang-format
        files: \.(cpp|h|hpp)$

然后安装钩子：

bash 复制代码

pre-commit install

之后每次 git commit 都会自动格式化改动的 C/C++ 文件。如果格式不符合要求，提交会被阻止，需要重新 add 并提交。

3. clang-tidy：静态分析与代码检查

clang-tidy 是 C++ 项目的静态分析工具，能检查常见的错误、性能问题、现代 C++ 使用不当等。它基于 Clang 的 AST 进行诊断，支持大量检查器。

3.1 安装

clang-tidy 通常与 clang 编译器一同发布，也可以单独安装：

bash 复制代码

sudo apt install clang-tidy

建议使用与项目编译一致的 clang 版本，以保证检查结果的准确性。

3.2 基础用法与配置文件

在项目根目录放置 .clang-tidy：

yaml 复制代码

Checks: >
  -*,
  bugprone-*,
  performance-*,
  modernize-*,
  readability-*,
  cppcoreguidelines-*,
  -modernize-use-trailing-return-type
CheckOptions:
  - key: bugprone-argument-comment.StrictMode
    value: true
  - key: readability-identifier-naming.ClassCase
    value: CamelCase

运行检查：

bash 复制代码

clang-tidy main.cpp -- -I./include -std=c++17

其中 -- 之后是编译选项。通常需要指定头文件路径和 C++ 标准，否则可能因为分析不到完整上下文而产生误报。

3.3 结合 compilation database

对于大型项目，推荐使用 CMake 生成 compile_commands.json：

bash 复制代码

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..

然后运行 clang-tidy 时指定 -p 参数：

bash 复制代码

clang-tidy -p build/ main.cpp

clang-tidy 会自动解析编译数据库，获得准确的编译选项。

3.4 只检查改动的代码（增量扫描）

为了在 CI 中提升效率，可以结合 git diff 只对改动的文件或行进行检查。clang-tidy-diff 是该工具链的一部分：

bash 复制代码

git diff -U0 HEAD | clang-tidy-diff -p1 -path build/ -use-color

也可以借助其他脚本（如 run-clang-tidy）来批量处理，并过滤警告。

3.5 集成到 Pre-commit

类似的，将 clang-tidy 加入 pre-commit 配置：

yaml 复制代码

  - repo: https://github.com/pre-commit/mirrors-clang-tidy
    rev: v17.0.6
    hooks:
      - id: clang-tidy
        args: [-p=build/, -fix, -fix-errors]
        files: \.(cpp|h|hpp)$

其中 -fix 会自动修复可修复的问题（如 modernize-use-nullptr），而 -fix-errors 仅修复导致编译错误的检查。需谨慎使用自动修复，建议先在本地验证。

4. 实战建议与工作流

渐进式引入：对于存量项目，先仅对新增或修改的文件运行 clang-tidy，老代码暂时豁免，避免大量噪声。
统一配置 ：将 .clang-format、.clang-tidy 和 .pre-commit-config.yaml 提交到仓库，由 CI 强制执行。
与 IDE 集成：Clangd 插件（VSCode、CLion）可以读取这些配置文件，在编码时实时提示格式化问题和静态分析警告，前置发现问题。
CI 流水线：在 GitHub Actions、GitLab CI 或 Jenkins 中增加步骤，即使开发者未启用 pre-commit，CI 也会拒绝不符合格式或存在严重警告的代码合入。
自定义检查器：如果内部有特定编码规范，可以编写 clang-tidy 插件，作为企业级代码标准的一部分。

5. 总结

clang-format 和 clang-tidy 是现代 C++ 工程化中不可或缺的工具。通过 Git 前置钩子与 CI 流水线配合，能将代码风格统一和常见缺陷检测前置到提交环节，显著提升团队开发效率和代码质量。从最小配置开始，逐步调整规则，团队很快就会感受到自动化带来的收益。