准备工作与环境
安装与版本要求
在 C++ 静态分析领域，Clang-Tidy 是提升代码质量与编码规范的核心工具之一。它基于 LLVM/Clang 构建，提供丰富的检查项、可扩展性强，并能与编译信息高度对齐，从而更准确地定位问题。确保使用的版本兼容你的编译器与工具链，并确认系统中已安装 clang-tidy 的可执行文件路径。
要充分发挥 Clang-Tidy 的能力，需要一个稳定的编译命令数据库。compile_commands.json 记录了每个源文件的编译参数，是实现高精度分析的关键。建议通过项目的构建配置生成该文件，以便后续的分析结果具有可重复性和可追溯性。
# 通过 CMake 生成 compile_commands.json
cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
# 验证文件是否就位
ls -l build/compile_commands.json
集成开发环境的配置
大多数 IDE/编辑器都提供对 Clang-Tidy 的原生支持或插件集成，使得在编码时即可看到诊断结果。IDE 集成可以在保存时触发检查、显示警告、并跳转到问题所在的代码行，明显提升工作效率。
如果偏好命令行，也可以手动运行 clang-tidy 进行逐文件分析，并通过 -p 指定编译数据库所在目录，确保头文件与编译选项的正确解析。
# 逐文件分析示例（需要 compile_commands.json）
clang-tidy src/main.cpp -p build -checks=modernize-*,readability-*
核心工作流与命令
基本用法
最常用的起步方式是对一个或多个源文件进行检查。检查集的选择直接决定覆盖的规则范围，常从可读性、现代化改造以及潜在错误等方向入手，逐步提高代码质量与编码规范的一致性。
为了保证结果可控，建议在项目根目录放置一个全局配置，例如 .clang-tidy，并通过命令行结合 -p 指定构建目录来读取编译信息。
# 针对单个文件进行分析
clang-tidy src/utils.cpp -p build -checks=modernize-*,readability-*
# 先确保编译命令数据库存在，然后对多源文件分析
cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
clang-tidy src/*.cpp -p build -checks=modernize-*,readability-*
批量分析与自动化
对于大型代码库，批量分析更具实用性，可结合构建系统来实现可重复的检查。通过对构建目录读取 compile_commands.json，可以对整仓库内的源文件进行统一的诊断。
在日常开发中，可以把检查范围逐步扩展到不同子模块，并在 CI 流程中持续应用。
# 对目标目录下的所有源文件进行分析（需生成 compile_commands.json）
clang-tidy src/module1/*.cpp src/module2/*.cpp -p build -checks=readability-*,bugprone-*
修复与自动修复
部分检测到的问题支持自动修复，使用 -fix 选项可以让 Clang-Tidy 尝试应用替换结果。不过，自动修复后仍需人工复核，以避免引入新的问题。
在启用自动修复前，推荐先做一个可回滚的版本控制提交，确保对比变更与回滚都可控。
# 启用自动修复
clang-tidy src/algorithm.cpp -p build -checks=modernize-*,readability-* -fix
常用规则集与自定义配置
官方规则与自定义配置
Clang-Tidy 提供成百上千的检查项，常用的入口包括 modernize-*、readability-*、bugprone-*、performance-* 等类型。通过在 .clang-tidy 中配置 Checks，可以灵活组合需要的规则集合，并通过 CheckOptions 定义具体的命名、风格等约束，达到统一编码规范的目的。
下面给出一个简化的配置示例，帮助实现一个可扩展的检查集，且可按需要逐步扩充。
---
Checks: 'modernize-*,readability-*,bugprone-*,performance-*'
WarningsAsErrors: ''
CheckOptions:- key: readability-identifier-naming.VariableCasevalue: 'lower_case'- key: readability-identifier-naming.FunctionCasevalue: 'CamelCase'
如何在大型仓库中组织规则
对于多语言、跨模块的大型仓库，可以通过分模块的 .clang-tidy 配置，结合根目录的统一规则，逐步覆盖到各子模块。局部化配置有助于减少全局性冲突，并便于对特定领域代码应用更严格的检查。
在实际场景中，配合编译命令的一致性，可以确保各子模块的头文件与实现文件在风格与命名上的一致性，从而显著提升代码的可读性与可维护性。
将 Clang-Tidy 融入 CI/CD
在构建系统中集成
将 Clang-Tidy 作为持续集成的一环，可以在每次提交或合并请求时自动对代码进行静态分析，确保新提交不偏离目标的编码规范。CI 端的统一检查有助于早期发现潜在问题，降低后续重构成本。
为保证分析结果的一致性，推荐在 CI 流程中新建一个独立的分析阶段，并保持 compile_commands.json 的可用性，以确保分析与实际编译条件一致。
name: Clang-Tidy Analysis
on: [ push, pull_request ]
jobs:clang-tidy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- name: Install LLVM/Clang-Tidyrun: sudo apt-get update && sudo apt-get install -y clang-tidy- name: Run clang-tidyrun: clang-tidy src/**/*.cpp -p build -checks=modernize-*,readability-*
示例：GitHub Actions / GitLab CI
在 GitHub Actions 或 GitLab CI 的工作流中，直接将 clang-tidy 的执行嵌入到构建阶段，可以实现对新增代码的持续静态分析。持续集成中的静态分析结果通常以日志、报告或直接的变更形式反馈给开发者，并推动代码质量的提升。
下列示例展示了一个常见的 GitHub Actions 配置，在其中安装了 Clang-Tidy，并对源码进行检查。
# .github/workflows/clang-tidy.yml
name: Clang-Tidy
on: [push, pull_request]
jobs:clang-tidy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- name: Install LLVM/Clang-Tidyrun: sudo apt-get update && sudo apt-get install -y clang-tidy- name: Run clang-tidyrun: clang-tidy src/**/*.cpp -p build -checks=modernize-*,readability-*
通过将分析结果与代码变更对齐，团队协作效率提升，并且可以把常见的代码风格问题逐步纳入到日常开发流程中。
