在 Cursor 中设置 C++ 质量门：3 项自动化检查

C++ 开发需要严格的质量控制。本指南向您展示如何在 Cursor 中设置三项自动化检查，在每次提交前运行：目标构建、清理器构建和使用 cppcheck 的静态分析。结合 Git pre-push 钩子，这些检查确保您的代码始终处于生产就绪状态。

三项检查

检查 1：目标构建

使用与部署环境相同的设置编译代码。

检查 2：清理器构建

运行 AddressSanitizer (ASan) 和 UndefinedBehaviorSanitizer (UBSan) 以捕获内存错误和未定义行为。

检查 3：静态分析

使用 cppcheck 在不运行代码的情况下发现错误、风格违规和潜在问题。

先决条件

安装所需工具：

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential cmake cppcheck

# macOS
brew install cmake cppcheck

# Windows（通过 MSYS2 或 WSL）
pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-cppcheck

项目结构

my-cpp-project/
├── src/
│   ├── main.cpp
│   └── utils.cpp
├── include/
│   └── utils.h
├── tests/
│   └── test_main.cpp
├── CMakeLists.txt
├── .cursor/
│   └── quality-gate.sh
└── .git/hooks/
    └── pre-push

步骤 1：CMake 配置

创建包含构建配置文件的 CMakeLists.txt：

cmake_minimum_required(VERSION 3.14)
project(MyProject CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 源文件
add_executable(myapp
    src/main.cpp
    src/utils.cpp
)

target_include_directories(myapp PRIVATE include)

# 目标构建配置文件（类似生产环境）
add_library(target_profile INTERFACE)
target_compile_options(target_profile INTERFACE
    -O2
    -DNDEBUG
    -Wall
    -Wextra
    -Werror
)

# 清理器构建配置文件
add_library(sanitizer_profile INTERFACE)
target_compile_options(sanitizer_profile INTERFACE
    -O1
    -g
    -fsanitize=address,undefined
    -fno-omit-frame-pointer
)
target_link_options(sanitizer_profile INTERFACE
    -fsanitize=address,undefined
)

# 应用配置文件
option(USE_SANITIZER "Build with sanitizers" OFF)
if(USE_SANITIZER)
    target_link_libraries(myapp sanitizer_profile)
else()
    target_link_libraries(myapp target_profile)
endif()

# 测试
enable_testing()
add_executable(myapp_tests tests/test_main.cpp)
target_link_libraries(myapp_tests target_profile)
add_test(NAME unit_tests COMMAND myapp_tests)

步骤 2：质量门脚本

创建 .cursor/quality-gate.sh：

#!/bin/bash
set -e

PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
BUILD_DIR="$PROJECT_ROOT/build"
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # 无颜色

echo "=========================================="
echo "  Cursor C++ Quality Gate"
echo "=========================================="

# 清理构建目录
rm -rf "$BUILD_DIR"
mkdir -p "$BUILD_DIR"

# 检查 1：目标构建
echo -e "\n${YELLOW}[1/3] 目标构建${NC}"
echo "使用生产设置构建..."
mkdir -p "$BUILD_DIR/target"
cd "$BUILD_DIR/target"
cmake ../.. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
echo -e "${GREEN}目标构建：通过${NC}"

# 运行测试
echo "运行测试..."
ctest --output-on-failure
echo -e "${GREEN}测试：通过${NC}"

# 检查 2：清理器构建
echo -e "\n${YELLOW}[2/3] 清理器构建${NC}"
echo "使用 AddressSanitizer 和 UBSan 构建..."
mkdir -p "$BUILD_DIR/sanitizer"
cd "$BUILD_DIR/sanitizer"
cmake ../.. -DCMAKE_BUILD_TYPE=Debug -DUSE_SANITIZER=ON
make -j$(nproc)

echo "使用清理器运行..."
./myapp || {
    echo -e "${RED}清理器检测到错误！${NC}"
    exit 1
}
echo -e "${GREEN}清理器构建：通过${NC}"

# 检查 3：静态分析
echo -e "\n${YELLOW}[3/3] 静态分析 (cppcheck)${NC}"
cd "$PROJECT_ROOT"

cppcheck \
    --enable=all \
    --suppress=missingIncludeSystem \
    --error-exitcode=1 \
    --inline-suppr \
    --check-config \
    -I include \
    src/ \
    tests/ \
    2>&1 | tee "$BUILD_DIR/cppcheck-report.txt"

echo -e "${GREEN}静态分析：通过${NC}"

# 摘要
echo -e "\n=========================================="
echo -e "${GREEN}所有质量门均已通过！${NC}"
echo "=========================================="
echo "构建产物：$BUILD_DIR/"
echo "报告：$BUILD_DIR/cppcheck-report.txt"

使其可执行：

chmod +x .cursor/quality-gate.sh

步骤 3：Git Pre-Push 钩子

创建 .git/hooks/pre-push：

#!/bin/bash

echo "在推送前运行质量门..."

if [ -f ".cursor/quality-gate.sh" ]; then
    bash .cursor/quality-gate.sh
    exit $?
else
    echo "警告：未找到质量门脚本"
    exit 0
fi

使其可执行：

chmod +x .git/hooks/pre-push

步骤 4：Cursor 集成

添加到 Cursor 任务

创建 .vscode/tasks.json（Cursor 使用 VS Code 任务系统）：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "C++ Quality Gate",
      "type": "shell",
      "command": "bash",
      "args": [".cursor/quality-gate.sh"],
      "group": {
        "kind": "test",
        "isDefault": true
      },
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "shared"
      },
      "problemMatcher": ["$gcc"]
    },
    {
      "label": "Quick Build",
      "type": "shell",
      "command": "cmake",
      "args": ["--build", "build/target", "--parallel"],
      "group": "build"
    },
    {
      "label": "Run Sanitizer Build",
      "type": "shell",
      "command": "bash",
      "args": ["-c", "mkdir -p build/sanitizer && cd build/sanitizer && cmake ../.. -DUSE_SANITIZER=ON && make -j$(nproc) && ./myapp"],
      "group": "test"
    }
  ]
}

键盘快捷键

添加到 .vscode/keybindings.json：

[
  {
    "key": "ctrl+shift+q",
    "command": "workbench.action.tasks.runTask",
    "args": "C++ Quality Gate"
  }
]

理解清理器输出

AddressSanitizer (ASan)

检测：

• 释放后使用
• 堆缓冲区溢出
• 栈缓冲区溢出
• 全局缓冲区溢出
• 返回后使用
• 作用域后使用
• 双重释放
• 内存泄漏

示例输出：

==12345==ERROR: AddressSanitizer: heap-buffer-overflow
READ of size 4 at 0x602000000014 thread T0
    #0 0x5555555551a9 in main src/main.cpp:15

UndefinedBehaviorSanitizer (UBSan)

检测：

• 有符号整数溢出
• 除以零
• 空指针解引用
• 未对齐指针访问
• 无效移位操作

示例输出：

src/utils.cpp:42:15: runtime error: signed integer overflow

自定义 cppcheck

抑制注释

在代码中：

// cppcheck-suppress unusedFunction
void debugHelper() {
    // 仅在调试构建中使用
}

// cppcheck-suppress knownConditionTrueFalse
if (x == x) {  // 故意检查 NaN
    // 处理 NaN
}

配置文件

创建 cppcheck-suppressions.txt：

unusedFunction:*test*
missingIncludeSystem
unmatchedSuppression

更新脚本：

cppcheck \
    --enable=all \
    --suppressions-list=cppcheck-suppressions.txt \
    --error-exitcode=1 \
    src/ tests/

CI/CD 集成

GitHub Actions

name: C++ Quality Gate

on: [push, pull_request]

jobs:
  quality-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y build-essential cmake cppcheck
      
      - name: Run Quality Gate
        run: bash .cursor/quality-gate.sh

故障排除

问题	解决方案
清理器构建太慢	使用 -O1 而不是 -O0 以加快构建速度
cppcheck 误报	添加抑制注释或配置文件
钩子未运行	确保 .git/hooks/pre-push 可执行
构建期间内存不足	减少并行任务：make -j2 而不是 -j$(nproc)

快速参考

# 运行完整质量门
bash .cursor/quality-gate.sh

# 仅快速目标构建
mkdir -p build && cd build && cmake .. && make -j$(nproc)

# 使用清理器运行
mkdir -p build-san && cd build-san && cmake .. -DUSE_SANITIZER=ON && make -j$(nproc) && ./myapp

# 仅运行 cppcheck
cppcheck --enable=all --error-exitcode=1 src/

相关资源

• Debug C++ with Breakpoints in Cursor
• Cursor and JetBrains Compatibility
• Handling Large Projects with Cursor