第一阶段选择 Docusaurus 和 TypeScript，先完成稳定的内容结构、测试基线与本地构建。部署方式、复杂主题切换和私人内容系统暂不纳入范围。

这是一个集原理讲解、场景复现和解决方案于一体的完整指南。通过本项目提供的工具，你可以亲手复现 macOS Gatekeeper 的拦截行为，并彻底理解 “应用已损坏” (App Damaged) 背后的技术真相。

1. 现象描述​

在 macOS 上安装或启动应用时，可能会遇到以下提示：

“xxx.app 已损坏，无法打开。你应该将它移到废纸篓。” (English: "xxx.app is damaged and can't be opened. You should move it to the Trash.")

核心事实： 大多数情况下，文件并没有物理损坏。这通常是 macOS 的 Gatekeeper 安全机制在发现应用“来路不明”（如带有隔离属性且无有效签名）时，为了安全起见直接拒绝运行的通用错误提示。

2. 核心原理：两道防线​

macOS 的应用启动检查可以看作是两道防线：

1. 第一道防线：内核 (Kernel) —— 强制代码签名

   • 机制：在 M1/M2/M3 (Apple Silicon) 芯片上，所有可执行代码必须拥有签名（哪怕是 Ad-hoc 签名）。
   • 拦截表现：如果完全无签名，内核直接拒绝加载，进程崩溃（Killed）。
   • 豁免：本地编译生成的文件会有临时的 AMFI 豁免，但一旦文件离开本机（异地），豁免失效，必须有签名才能活。

2. 第二道防线：Gatekeeper —— 信任策略检查

   • 触发开关：隔离属性 (Quarantine)。当文件来自非本地来源（如下载、AirDrop）时，系统会自动添加此属性。一旦检测到此属性，Gatekeeper 即会介入。
   • 检查内容：
     • 是不是正经开发者？ (是否有 Apple Developer ID)。
     • 有没有恶意软件？ (是否经过公证 Notarized)。
     • 文件改没改过？ (哈希校验)。
   • 拦截表现：提示“无法验证开发者”或“应用已损坏”。

总结：

• 无签名 -> 死在第一道防线（内核）。
• Ad-hoc + 隔离 -> 死在第二道防线（Gatekeeper）。
• 文件篡改 -> 死在哈希校验（Gatekeeper）。

3. 验证实验室：亲自复现与验证​

为了验证上述原理，我们编写了一个简单的验证工具包。这里包含了 6 个核心实验，覆盖了 macOS 下应用运行的所有关键场景。

实验概览表​

项目结构​

📦 完整项目代码：macos-gatekeeper-guide

macos-gatekeeper-guide/
├── build_test_app.sh # 构建脚本（支持多种签名模式）
├── src/
│ └── main.swift # 测试应用源码（SwiftUI）
└── build/ # 构建产物目录（自动生成）
└── \*.app # 生成的测试应用

核心文件说明：

• build_test_app.sh：一键构建工具，支持 --unsigned、--linker-signed、--name 等参数
• src/main.swift：极简 SwiftUI 应用，用于验证签名和 Gatekeeper 行为

使用前提：确保在项目根目录下执行所有命令。

实验 1：本地无签名（基准对照）​

验证 macOS 对“本机生产”文件的信任机制。

1. 构建无签名应用：

   ./build_test_app.sh --unsigned --name "App_Exp1"
   

   (说明：此处的 --unsigned 会显式移除所有签名，包括 Linker-Signed（编辑器自动添加的签名）。)
2. 运行：双击 build/App_Exp1.app。

结果：✅ 成功打开。

原理：本机编译的文件享有 AMFI 临时豁免，即使完全无签名也能运行。

实验 2：异地无签名 + 移除隔离（模拟尝试绕过）​

验证如果用户手动移除了隔离属性，完全无签名的应用在异地是否能运行。

1. 构建无签名应用：

   ./build_test_app.sh --unsigned --name "App_Exp2"
   

2. 通过 AirDrop 传输到另一台 Mac。
3. 在接收机器上移除隔离属性：

   xattr -d com.apple.quarantine /path/to/App_Exp2.app
   

4. 运行：双击 App_Exp2.app。

结果：❌ 无法打开 / 闪退。

• 注意：此时在“隐私与安全性”中不会出现“仍要打开”的按钮。
• 原理：因为隔离属性已被移除，Gatekeeper 没有介入，是内核直接查杀了进程。

实验 3：异地完整 Ad-hoc + 无隔离（成功绕过方案）​

验证 Ad-hoc 签名在移除隔离属性后的行为。

1. 构建完整 Ad-hoc 应用：

   ./build_test_app.sh --name "App_Exp3"
   

2. 通过 AirDrop 传输到另一台 Mac。
3. 在接收机器上移除隔离属性：

   xattr -d com.apple.quarantine /path/to/App_Exp3.app
   

4. 运行：双击 App_Exp3.app。

结果：✅ 成功打开。

结论：完整 Ad-hoc + 移除隔离 = 可行。 内核只要求“有签名”，Gatekeeper 只要求“有隔离才查”。只要移除了隔离，Gatekeeper 不上班，内核看到有签名就放行。

实验 4：异地 Ad-hoc + 有隔离（标准拦截）​

这是最真实的默认场景：你写了个 App（未购买证书），直接分发给他人使用。

1. 构建：

   ./build_test_app.sh --name "App_Exp4"
   

2. 通过 AirDrop 传输到另一台 Mac（自动添加隔离属性）。
3. 运行：双击 build/App_Exp4.app。

结果：⚠️ 被拦截 / 提示无法验证开发者。

• 关键点：由于我们的构建脚本使用了规范的 codesign，签名结构完整。因此，在“隐私与安全性”设置中，会出现“仍要打开”按钮，允许用户手动放行。

点击仍要打开，打开成功

实验 5：自动隔离机制演示​

验证到底什么操作会给文件贴上“隔离”标签。

验证步骤​

1. 使用 curl 下载（纯命令行）：

   curl -o google.png https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png
   
   xattr -l google.png
   # 结果：(无输出，表示无属性)
   

2. 使用 Safari/Chrome 下载同一张图：

   xattr -l ~/Downloads/googlelogo_color_272x92dp.png
   # 输出示例：
   # com.apple.quarantine: 0081;693a85a3;Chrome;632447E8-28E3-443B-B2D8-FA423C6B2384
   

3. 使用 AirDrop 接收文件。

   xattr -l ~/Downloads/googlelogo_color_272x92dp.png
   # 输出示例：
   # com.apple.quarantine: 0081;655...;sharingd;...
   

4. 微信传输：

   xattr -l ~/Downloads/googlelogo_color_272x92dp.png
   # 输出示例：
   # com.apple.quarantine:0082;693a8446;WeChat;
   

原理：

• 隔离属性由 macOS 的 Launch Services 框架自动添加
• 当应用（如浏览器、AirDrop、微信）通过特定 API 下载或接收文件时，会触发 Launch Services 标记
• 命令行工具（curl、wget）直接写入文件系统，不经过这些 API，因此不会触发标记
• 隔离属性包含来源信息（下载工具名称、时间戳、URL 等），用于追溯文件来源

实验 6：签名完整性实验（解密“仍要打开”消失之谜）​

能够解释为什么同样的 Ad-hoc 签名，有的能点“仍要打开”，有的直接报“已损坏”。

1. 第一阶段：构建“残血版” (硬拦截) 使用 --linker-signed 参数，构建一个仅包含 Linker 签名但没有资源密封（Sealed Resources）的应用。

   ./build_test_app.sh --linker-signed --name "App_Exp6_Bad"
   # 手动添加隔离属性（模拟下载）
   xattr -w com.apple.quarantine "0081;632447E8;Chrome;" build/App_Exp6_Bad.app
   

   结果：双击运行 -> ❌ “应用已损坏” (无按钮)。

   

2. 第二阶段：修复为“满血版” (软拦截) 对同一个 App 进行规范签名。

   codesign --code --force --deep --sign - --verbose=4 build/App_Exp6_Bad.app
   

   结果：双击运行 -> ⚠️ “无法验证开发者” -> 设置中出现 【仍要打开】 按钮。

   

   点击 OK（确定），弹出 Open Anyway(仍要打开)

   点击仍要打开，打开成功

结论：签名结构完整性决定了是“硬拦截（已损坏）”还是“软拦截（无法验证）”。

4. 深度辨析：硬拦截 vs 软拦截​

通过实验 6，我们知道了签名结构的重要性。那么如何查看应用的签名状态呢？

查看签名信息​

使用 codesign 命令可以查看应用的详细签名信息：

# 查看签名详情
codesign -dvvv /path/to/Your.app

# 关键输出示例：
# Linker-Signed（残缺）:
#   Sealed Resources=none
#
# 完整 Ad-hoc:
#   Sealed Resources=version 2 rule count=13 nested=0

硬拦截 vs 软拦截对比​

如何确诊？ 使用日志查看确切错误：

log stream --predicate 'process == "syspolicyd"' --info

• 硬拦截 (-67062)：签名结构无法满足要求（如 Linker-Signed 加了隔离）。
• 软拦截: 系统尝试获取授权，允许用户手动批准。

5. 用户端解决方案（按推荐程度排序）​

✅ 方案 A：终端命令解除隔离​

这是根治“已损坏”且适用性最广的方法（前提：App 有起码的签名）。

# 递归删除隔离属性
xattr -r -d com.apple.quarantine /path/to/Your.app

⚠️ 方案 B：“仍要打开”​

• 适用：签名完整但无 Developer ID 的应用。
• 操作：系统设置 -> 隐私与安全性 -> 点击【仍要打开】。

🚫 方案 C：开启“任何来源”​

sudo spctl --master-disable

(这无法解决内核级的签名缺失问题，不推荐)

6. 开发者根治方案​

如果您是开发者，想要分发应用且确保用户100% 不遇到此问题：

🔑 唯一正道：签名 + 公证​

1. 购买：Apple Developer Program ($99/年)。
2. 签名：使用 Developer ID Application 证书签名。
3. 公证 (Notarize)：提交给 Apple 服务器进行恶意软件扫描，并获取 Ticket。

📦 分发建议​

• 推荐 DMG：虽然也会带有 Quarantine，但由于是只读镜像，它能确保文件权限和结构绝对完整。只要用户通过上述方案绕过 Quarantine，App 是一定能跑的。
• 慎用 Zip：如果用户解压工具不当，可能会丢失可执行权限或破坏 Bundle，导致“真·损坏”。

一、传统指针基础​

基本概念​

指针存储内存地址，通过 * 解引用，& 取地址。

int val = 42;
int* ptr = &val;           // ptr 存储 val 的地址
*ptr = 100;                // 通过指针修改 val 的值

// 指针的 const 修饰
const int* c_ptr = &val;   // 指向常量:不能通过指针修改值
int* const ptr_c = &val;   // 常量指针:指针本身不能改变指向

动态内存管理​

使用 new/delete 在堆上分配和释放内存,必须成对使用。

void dynamicMemory() {
    int* obj = new int(42);      // 分配单个对象
    int* arr = new int[5]{0};    // 分配数组

    // 使用完毕后释放
    delete obj;   obj = nullptr;
    delete[] arr; arr = nullptr; // 数组必须用 delete[]
}

常见陷阱​

传统指针的问题

手动管理内存容易出错,异常安全性差。现代 C++ 推荐使用智能指针自动管理生命周期。

二、智能指针:自动内存管理​

C++11 引入 <memory> 头文件,提供三种智能指针,利用 RAII 机制自动管理资源。

std::unique_ptr - 独占所有权​

最常用的智能指针,零开销,确保资源只有一个拥有者。

#include <memory>

void uniquePtrDemo() {
    // 推荐使用 make_unique 创建
    auto ptr = std::make_unique<int>(100);

    // 独占特性:不可复制,只能移动
    // auto p2 = ptr;           // ❌ 编译错误
    auto p2 = std::move(ptr);   // ✅ 转移所有权,ptr 变为 nullptr

    // 数组支持
    auto arr = std::make_unique<int[]>(5);

    // 自定义删除器(如关闭文件句柄)
    auto file = std::unique_ptr<FILE, decltype(&fclose)>(
        fopen("test.txt", "w"), &fclose
    );
} // 离开作用域自动释放

std::shared_ptr - 共享所有权​

使用引用计数,允许多个指针共享同一资源,最后一个持有者销毁时释放资源。

void sharedPtrDemo() {
    auto p1 = std::make_shared<int>(42); // 引用计数 = 1
    {
        auto p2 = p1;  // 引用计数 = 2
        std::cout << *p2;
    } // p2 销毁,引用计数 = 1

    // p1 依然有效
} // p1 销毁,引用计数 = 0,资源释放

为什么用 make_shared? make_shared 只分配一次内存(对象 + 控制块),而 shared_ptr(new T) 需要两次分配,效率更低。

std::weak_ptr - 弱引用​

不增加引用计数,用于打破循环引用或实现观察者模式。

解决循环引用:

struct Node {
    std::shared_ptr<Node> next;
    std::weak_ptr<Node> prev; // ✅ 用 weak_ptr 打破循环
    ~Node() { std::cout << "Node 析构\n"; }
};

void noCycle() {
    auto n1 = std::make_shared<Node>();
    auto n2 = std::make_shared<Node>();
    n1->next = n2;
    n2->prev = n1; // 如果 prev 是 shared_ptr,会导致循环引用
} // 正常析构

安全访问:

std::weak_ptr<int> wp;
{
    auto sp = std::make_shared<int>(42);
    wp = sp;
    if (auto locked = wp.lock()) { // 尝试升级为 shared_ptr
        std::cout << *locked;      // 对象存在,可以访问
    }
}
// sp 销毁后,wp.lock() 返回 nullptr

三、实战:成员变量设计​

默认选择:直接实例​

原则:能用值类型就用值类型,简单可靠。

class Car {
    Engine engine;  // ✅ 推荐:生命周期自动绑定
public:
    Car() : engine(2.0) {} // 初始化列表构造
};

优点:

• 内存连续,缓存友好
• 生命周期自动管理
• 无空指针风险

何时使用指针?​

示例:多态容器

class Zoo {
    std::vector<std::unique_ptr<Animal>> animals;
public:
    void add(std::unique_ptr<Animal> animal) {
        animals.push_back(std::move(animal));
    }
};

四、高级:混用场景与陷阱​

在实际项目中,常遇到原始指针、智能指针、Qt 对象混用,这是最容易出错的地方。

核心原则​

谁创建谁拥有,谁拥有谁删除。一个资源只能有一个"主人"。

场景 1:标准 C++ - 智能指针与原始指针​

规则:智能指针拥有所有权,原始指针仅用于观察。

void process(MyClass* ptr) { // 接收原始指针
    if (ptr) ptr->doSomething();
    // ❌ 绝对不要 delete ptr
}

void caller() {
    auto owner = std::make_unique<MyClass>();
    process(owner.get()); // 借用给函数
} // owner 离开作用域,自动释放

场景 2:Qt 父子对象机制​

Qt 使用对象树自动管理 QObject 及其派生类的内存。

规则:

• 有 parent 的对象由 parent 负责释放
• 使用原始指针,不要 delete,不要用智能指针

void createWidget() {
    QWidget* parent = new QWidget();
    QPushButton* btn = new QPushButton("Click", parent); // 指定 parent
    // 不需要 delete btn,parent 析构时会自动释放
}

场景 3:纯 C++ 对象在 Qt 项目中​

不继承 QObject 的类不享受 Qt 内存管理,必须手动管理。

class MyData { /* 普通 C++ 类 */ };

void qtFunction() {
    // ❌ 错误:内存泄漏!
    MyData* data = new MyData();

    // ✅ 正确:使用智能指针
    auto safeData = std::make_unique<MyData>();
}

场景 4:QML 与 C++ 混合开发​

所有权取决于对象的创建方式:

示例:QML 声明式创建

Rectangle {
    CircuitPainter { // C++ 注册的类
        id: painter
    }
}

class CircuitPainter : public QQuickPaintedItem {
    QVector<Wire*> m_wires;  // Wire 对象没有 parent
public:
    ~CircuitPainter() {
        // CircuitPainter 自身由 QML 管理（有父对象 Rectangle）
        // 但 m_wires 里的 Wire* 对象没有 parent，必须手动清理
        qDeleteAll(m_wires);
    }
};

:::tip 关键区分

• CircuitPainter 自身：由 QML 父对象（Rectangle）管理，QML 会自动释放
• m_wires 成员：里面的 Wire* 对象没有指定 parent，必须在析构函数中手动清理 :::

致命陷阱:Qt 与智能指针混用​

❌ 错误:智能指针管理 Qt 子对象

{
    QWidget* parent = new QWidget();
    // 错误!unique_ptr 和 parent 都会尝试 delete btn
    std::unique_ptr<QPushButton> btn(new QPushButton(parent));
} // CRASH! Double Free

✅ 正确做法:

1. 有 parent 的 QObject:用原始指针,交给 Qt 管理
2. 无 parent 的 QObject:可用 std::unique_ptr 或 QScopedPointer
3. 非 QObject 类:优先用 std::unique_ptr / std::shared_ptr

五、指针选择速查表​

六、最佳实践​

1. 优先使用 make_unique / make_shared:更安全、更高效
2. 原始指针仅用于观察:不拥有所有权,不负责 delete
3. 明确所有权语义:
   • 函数参数用引用 (T&) 或原始指针 (T*)
   • 需要转移所有权时用 unique_ptr
   • 需要共享所有权时用 shared_ptr
4. Qt 开发特例:有 parent 的 QObject 只用原始指针
5. 初始化原始指针:务必初始化为 nullptr

现代 C++ 原则 除非别无选择,否则不要手动调用 delete。

在 Qt 中,相信 Parent 机制。

1. settings.json：编辑器配置​

作用：控制编辑器行为（当前工作区级别，优先级高于全局设置）。

示例：

// .vscode/settings.json
{
  "editor.formatOnSave": true, // 保存时自动格式化
  "editor.tabSize": 2, // 缩进大小
  "files.exclude": {
    // 隐藏特定文件
    "**/.git": true,
    "**/.DS_Store": true
  },
  "search.exclude": {
    // 搜索时排除
    "**/node_modules": true
  }
}

2. tasks.json：任务自动化​

作用：将命令行脚本集成到编辑器中。不同语言的配置方式略有差异（如 Node.js 用 npm 类型，C++/Rust 用 shell 类型），但核心都是为了支持通过快捷键一键调用。

2.1 Node.js 项目示例 (npm)​

定义一个 npm test 任务，并让 npm build 依赖它（即构建前自动测试）。

// .vscode/tasks.json
{
  "version": "2.0.0", // 推荐版本
  "tasks": [
    {
      "label": "npm: build",
      "type": "npm", // 任务类型：自动识别 package.json
      "script": "build", // 对应 scripts.build (自动执行 npm run build)
      "dependsOn": ["npm: typecheck"], // 依赖项：先运行 typecheck，成功后再运行 build
      "group": {
        "kind": "build", // 归类为“构建任务” (Cmd+Shift+B 专用)
        "isDefault": true // 设为默认，按快捷键直接运行，不弹窗选择
      },
      "problemMatcher": ["$tsc"] // 捕获 TS 错误并在代码中高亮
    },
    {
      "label": "npm: typecheck",
      "type": "npm",
      "script": "typecheck",
      "group": "test" // 归类为“测试任务” (可通过 Run Test Task 查找)
    }
  ]
}

2.2 C++ 项目示例 (Shell)​

C++/Rust 等项目通常使用 shell 类型直接调用编译器。

{
  "label": "build cpp",
  "type": "shell", // 任务类型：直接在终端运行命令
  "command": "g++", // 命令
  "args": ["-g", "main.cpp", "-o", "main"], // 参数
  "group": {
    "kind": "build",
    "isDefault": true
  }
}

2.3 核心概念解析​

• type：决定任务的执行方式。
  • "npm", "gulp", "grunt" 等: 智能模式。VS Code 插件提供的特定类型，能自动识别配置文件并补全命令。
  • "shell": 通用模式。直接在终端执行你指定的 command。
• kind：任务的身份分类。
  • "build": 标记为构建任务 -> Cmd+Shift+B 快捷键专用。
  • "test": 标记为测试任务 -> 方便筛选。
• dependsOn：任务依赖链。
  • 逻辑类似 &&：先执行依赖任务，成功后才执行当前任务。

2.4 使用方式​

1. 快捷键（推荐）：直接按 Cmd+Shift+B。
   • 因配置了 isDefault: true，会直接触发默认构建任务。
2. 命令面板：Cmd+Shift+P -> 输入 Run Task -> 选择任务。

3. launch.json：调试配置​

作用：配置调试器，支持断点、变量查看等。

示例：调试 Node.js 应用，并在启动前先运行构建任务。

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node", // 调试环境 (常用：node, chrome, python等, 想调试什么语言，就装对应的插件，然后这里填对应的类型。)
      "request": "launch", // 核心模式仅两种：launch (启动新进程) / attach (附加到已有进程)
      "name": "Debug App",
      "program": "${workspaceFolder}/dist/index.js", // 调试构建后的文件
      "preLaunchTask": "npm: build", // 选填：调试前是否先运行构建任务（如无需构建可删除行）
      "env": {
        "NODE_ENV": "development"
      }
    }
  ]
}

3.2 前端项目示例 (Vite/React/Vue)​

对于 Vite 项目，不需要构建。你只需要启动开发服务器 (npm run dev)，然后让 VS Code 连接到浏览器。

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome", // 调试浏览器
      "request": "launch",
      "name": "Debug Vite App",
      "url": "http://localhost:5173", // Vite 默认端口
      "webRoot": "${workspaceFolder}/src", // 源码目录
      "preLaunchTask": "npm: dev" // 选填：调试前是否先运行构建任务（如无需构建可删除此行）
    }
  ]
}

使用方式：

1. 打断点：在源码文件（如 src/index.js）的行号左侧点击，出现红点即为断点。
2. 启动调试：按 F5，或者点击左侧“运行和调试”图标 -> 选择 Debug App -> 点击绿色播放键。
3. 效果：VS Code 会先运行 npm: build，构建成功后自动启动调试器，程序运行到断点处会自动暂停，你可以查看变量状态。

总结​

• settings.json：管环境（怎么看、怎么写）。
• tasks.json：管动作（怎么构建、怎么跑脚本）。
• launch.json：管运行（怎么调试）。

三者结合：launch.json 通过 preLaunchTask 调用 tasks.json，在符合 settings.json 定义的环境中高效开发。

前置环境​

• 操作系统: macOS
• 代理工具: ClashX Meta

第一部分：网络连接问题​

1. 现象描述​

• 症状：登录 Antigravity Google 账号成功后跳转回客户端，界面无反应或一直加载。
• 核心矛盾：同一网络环境下，Chrome 浏览器可以正常访问 Google 服务，但 Antigravity 客户端却无法登录，即使开启了 Clash 的系统代理也无效。

2. 诊断步骤​

排查此类问题的第一步是判断 DNS 解析是否正常。由于浏览器和客户端应用（如 Node.js/Electron）处理网络请求的机制不同，我们需要使用命令行工具来模拟客户端行为。

使用 nslookup 诊断​

在终端执行以下命令：

nslookup accounts.google.com

结果分析：

• 错误配置（直连解析）：

  Server:		114.114.114.114
  Non-authoritative answer:
  Name:	accounts.google.com
  Address: 64.233.187.84  <-- 真实的 Google IP
  

  解读：命令返回了一个真实的 Google IP。这说明 DNS 请求走了系统默认 DNS，未被代理工具接管。

• 正确配置（Fake-IP）：

  Server:		198.18.0.2
  Non-authoritative answer:
  Name:	accounts.google.com
  Address: 198.18.0.x     <-- 虚假 IP (Fake-IP)
  

  解读：返回了 198.18.x.x 网段的 IP，说明 Clash 的 DNS 劫持已生效，流量成功进入代理通道。

3. 技术深究：为什么浏览器能用，App 却不行？​

这是一个常见的误区。浏览器和普通应用在处理代理时有本质区别。通过以下两个具体例子，你可以清晰地看到差异：

例子 1：浏览器访问（走代理配置）​

当你开启系统代理后，浏览器访问 https://accounts.google.com 的流程如下：

1. 用户输入 URL：https://accounts.google.com
2. 检查代理配置：浏览器发现配置了代理（例如 127.0.0.1:7890）。
3. 发送请求给代理：浏览器不进行本地 DNS 解析，直接将请求（包含域名）发送给代理服务器。
4. 代理服务器处理：
   • 代理软件（如 Clash）接收到请求。
   • 代理软件在远程服务器上进行 DNS 解析（获取到 Google 的真实 IP）。
   • 代理软件建立连接并转发数据。
5. 结果：连接成功。

例子 2：普通应用 / Electron / Node 程序（依赖系统 DNS → 最容易出问题）​

你运行一个 Node 服务或 Electron 应用（Antigravity 也是此类）： fetch("https://accounts.google.com")

Node 默认不会自动使用浏览器的代理配置，真实流程如下：

1. Node 程序发起请求：我要访问 accounts.google.com。
2. 本地 DNS 解析：
   • 请求发送给本机 DNS 服务器（例如 114.114.114.114 或路由器 DNS）。
   • 注意：如果未开启 TUN 模式或 DNS 劫持，这里走的是普通网络路径。
3. DNS 返回结果：
   • DNS 返回真实的 Google IP（例如 64.233.187.84）。
4. 尝试建立连接：
   • Node 尝试直接连接 64.233.187.84:443。
   • 由于国内网络环境，无法直连该 IP。
5. 结果：连接超时或失败。

这就是为什么浏览器能打开，但终端或应用却报错的原因。开启 Clash 的 TUN 模式并启用 DNS 劫持（Fake-IP）可以解决这个问题，因为它会让步骤 2 中的 DNS 解析返回一个虚假 IP，从而将流量“骗”进代理通道。

4. 解决方案​

要解决此问题，必须启用 Clash 的 DNS 劫持 和 TUN 模式。

步骤一：修正 Clash DNS 配置​

打开 Clash 配置文件（通常在 ~/.config/clash.meta 或通过 GUI 配置），确保 DNS 模块已启用：

dns:
  enable: true # 必须为 true
  ipv6: false
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip # 推荐使用 fake-ip 模式

步骤二：开启 TUN 模式​

在 ClashX Meta 界面中：

1. 找到 "TUN Mode" 开关并开启。
2. 如果提示需要权限，请输入系统密码安装辅助工具。

常见疑问：只开启 dns: enable: true 不开 TUN 模式行吗？​

不行。

• dns: enable: true：仅仅是让 Clash 启动了一个内部的 DNS 服务器。
• TUN 模式：负责将操作系统的所有网络流量（包括 DNS 查询）强行劫持并转发给 Clash。

如果你只开启了 DNS 功能但没有开启 TUN 模式（且没有手动修改系统 DNS 指向 Clash），操作系统依然会使用默认的 DNS（如路由器 DNS）。Node 程序的 DNS 请求根本不会到达 Clash，自然也就无法获取 Fake-IP，问题依旧存在。

💡 什么是 TUN 模式？

TUN 模式会在系统中创建一个虚拟网卡。操作系统会将所有网络流量（包括终端、应用、系统更新等）都发送给这个虚拟网卡，从而让 Clash 能够接管并处理本机的所有网络请求。它是实现“全局代理”和处理非浏览器应用流量的关键。

🤔 TUN 模式 vs 全局模式 (Global Mode) / 系统代理

• 系统代理 (System Proxy)：只是告诉软件“请使用这个代理”。但很多软件（如终端、Node、Java）会忽略这个设置，直接发起连接。
• 全局模式 (Global Mode)：这只是 Clash 内部的一种策略（即“凡是进来的流量统统走代理”）。但它不具备强制捕获流量的能力。如果 App（如 Node）忽略系统代理设置，直接向公网发起连接（即流量绕过了 Clash），那么 Clash 根本接触不到这些数据包，全局模式自然也就无法生效。
• TUN 模式：这是强制手段。它在网卡层截获所有流量。无论软件是否愿意走代理，流量都会被 TUN 捕获并交给 Clash 处理。

结论：解决 Antigravity/Node 问题必须用 TUN 模式，单纯开“全局模式”或“系统代理”通常无效。

第二部分：账号资格问题​

1. 现象描述​

网络问题解决后，登录可能遇到以下报错：

"Your current account is not eligible for Antigravity, because it is not currently available in your location."

2. 根因分析​

Antigravity 对账号归属地有严格限制。

• 误区：以为只要挂了新加坡/美国的 VPN 就能通过。
• 真相：Google 判定资格时，主要依据 Google 账号的归属地（Play Store 地区），而不仅仅是当前的 IP 地址。
• 案例：用户使用新加坡节点，但 Google 账号归属地为 香港 (Hong Kong)。由于香港不在 Antigravity 支持列表（支持列表通常包括美国、新加坡、台湾等），因此被拒绝。

3. 解决方案​

将 Google 账号的地区更改为支持的区域（推荐 新加坡）。

操作步骤​

1. 访问 Google 账号地区设置。

2. 更改区域。

3. 理由选择其他：填写理由建议： 为了提高通过率，建议强调“功能需求”而非“绕过限制”。可以使用以下模板：

   I need to change my account region to Singapore because the software/service I am using is only available in the Singapore region. My current region setting prevents me from downloading or updating this software. This is a functional requirement based on the software provider's region restriction.

   Please help update my account region to Singapore so I can continue using the service normally.

   成功率提示

   • 强调软件功能需求，通常会被视为合理请求。
   • 避免提及价格、支付或仅仅为了“翻墙”。
   • 通常不需要提供居住证明。

4. 等待审核（通常 1-2 个工作日）。

总结​

顺利登录 Antigravity 的终极清单：

1. 网络层：

   • Clash 配置中 dns: enable: true。
   • 开启 TUN 模式 (Fake-IP)。
   • 终端 nslookup accounts.google.com 返回虚假 IP。

2. 账号层：

   • 使用 新加坡 节点。
   • 确保 Google 账号归属地为 新加坡（或美国等支持地区）。

遵循以上步骤，你应该能够解决登录卡住或资格验证失败的问题。

1. Cursor 最佳实践清单​

1.1 制定 PRD 规划​

利用 Cursor 的 AI 生成产品需求文档（PRD.md），为项目指明方向与结构（在团队协作中，可由产品经理在飞书等平台维护完整 PRD（面向人），同时在项目仓库中维护简化版 PRD.md（面向开发与 AI））。

• 在 PRD.md 中对目标、用户故事、非功能需求、范围、成功度量做最小完备定义。
• 将关键决策条目化，减少提示歧义，避免历史“飘移”。

1.2 在项目添加 Cursor 配置规则​

• .cursorignore

  .cursorignore 用来告诉 Cursor 哪些文件或目录不要被索引或引用，从而提升性能并避免泄露敏感信息。

  # .cursorignore（精简示意）
  node_modules/
  dist/
  build/
  .tmp/
  .cache/
  coverage/
  
  .env.*
  *.pem
  *.key
  *.crt
  *.cert
  *.p12
  *.keystore
  

• rules

  规则文件用来指导 AI，每个规则文件使用 MDC（.mdc）格式编写，这种格式同时支持元数据和内容。在 Cursor 中打开 .mdc 文件后，可通过顶部的类型下拉菜单选择规则类型，该操作会自动更新 description、globs 和 alwaysApply 属性。

  规则类型	描述
  Always	始终包含在模型上下文中
  Auto Attached	当引用与某个 glob 模式匹配的文件时包含
  Agent Requested	提供给 AI，由其决定是否包含。必须提供描述
  Manual	只有在使用 @ruleName 明确提及时才会包含

  规则适用于 Chat 和 Inline Edit。已启用的规则会显示在 Agent 对话框的上下文管理栏（顶部）。

  • 可按模块拆分：
    • .cursor/rules/frontend.mdc
    • .cursor/rules/backend.mdc
    • .cursor/rules/tests.mdc

1.3 选择合适的 Agent 工作模式​

Cursor Agent 提供三种工作模式，适用于不同开发场景：

• Plan 模式（规划模式）：在编写代码前先生成详细的实现方案。Agent 会研究你的代码库、提出澄清问题，并生成可审阅的方案，你可以在开始构建前进行编辑。适合复杂任务、架构设计、大规模重构等需要系统性规划的场景。

  • 工作流程：
    1. Agent 提出澄清性问题以了解需求
    2. 检索代码库并收集相关上下文
    3. 制定完整实现计划（以虚拟文件形式呈现）
    4. 你可审阅、编辑计划
    5. 点击"构建该计划"开始实施
  • 计划保存：可保存到 .cursor/plans/ 目录，便于团队共享和文档化

• Agent 模式：直接自动执行任务（如批量重构、自动测试、快速实现），适合明确目标和批量操作场景。

• Ask 模式：以对话为主，适合需求澄清、方案讨论、探索式协作。

使用建议：

• 复杂任务/架构设计 → 优先用 Plan 模式，先规划后执行
• 明确的开发/测试/重构 → 用 Agent 模式，快速迭代
• 需求沟通/方案探讨 → 用 Ask 模式，深度对话

1.4 选择合适的 AI 模型​

主流模型区别与推荐场景：

• 实践建议：
  • 日常开发/测试：优先 GPT-4.1、Claude-4 Sonnet
  • 架构设计/复杂推理：可选 GPT-5、Claude-4 Opus
  • 快速实验/低成本：Gemini、Grok、o3/o4-mini
  • 多模态（图文/代码）：Gemini 2.5 Pro
• 可根据任务难度、上下文长度、成本灵活切换，优先保证结果质量和语境理解。

1.5 使用 @ 标签提供上下文​

通过合理使用 @File、@Web、@Code、@Terminal 等标签，将关键上下文信息注入 prompt，可显著提升 AI 的理解度与结果质量。例如：

• @File：指定具体文件内容或路径，适合代码变更、定位 bug、结构分析。
• @Code：直接引用代码片段，适合讨论实现细节、重构建议、单元测试。
• @Web：补充外部网页或文档链接，适合查阅 API、第三方库、设计规范。
• @Terminal：引入终端命令或运行结果，适合调试、构建、测试反馈。

建议：每次协作时，优先补充与目标相关的上下文标签，减少歧义，提升沟通效率。 此外，你也可以直接选中代码片段添加到对话，或将代码/文本复制粘贴到对话框，AI 同样能自动识别并应用这些上下文信息，无需额外标签。

1.6 TDD 驱动迭代（先测后码）​

• 先为关键用户流写测试（最开始失败），再最小实现直至通过。
• 单元测试覆盖组件输入/输出与边界；集成测试覆盖核心操作流（新增 → 勾选 → 删除 → 筛选/排序等）。
• 测试环境要保证用例隔离（如清理 localStorage、组件卸载等）。

1.7 自动运行​

• Auto-Run Mode 允许 Agent 在安全边界内自动执行任务，如跑测试、类型检查、Lint。
• 推荐默认 Ask Every Time；必要时仅对白名单命令自动运行：npm test（或 npm run test:watch）、npm run build（可选；如已配置 lint/typecheck 再加入）。
• 每次只围绕一个清晰目标：先加测试 → 跑测（红）→ 最小实现 → 跑测（绿）。
• 大改前先建分支并提交快照；限定可改目录与行数，超限需人工确认。

1.8 基于测试驱动策略构建迭代反馈循环​

在较大项目中，建议每完成一个阶段性功能后，设置 1–2 个关键集成测试作为 checkpoint。通过自动化测试及时发现并修复编码错误，既能保障项目安全边界，又能提升开发效率。AI 可根据测试结果自动定位并修复问题，实现高效迭代。

2. TodoList 实践案例​

本章节基于 TodoList 项目，详细记录每个开发阶段的具体操作步骤、命令和提示词。

2.1 第一步：制定 PRD 规划​

目标：明确产品需求和技术边界

具体操作：

创建 PRD.md 文件，定义：

• 用户故事（Given/When/Then 格式）
• 验收标准（如：输入验证、状态切换、数据持久化）
• 技术栈选择（React + TypeScript + Vite + Vitest）
• MVP 范围（核心组件：TodoItem、TodoEditor）

示例提示词：

帮我创建一个 TodoList 应用的 PRD.md，包含：
- 6个核心用户故事（增删改查、筛选、搜索）
- 每个故事的 Given/When/Then 验收标准
- 明确 MVP 边界，排除用户系统和多端同步

2.2 第二步：生成项目骨架​

目标：搭建可运行的开发环境

示例提示词：

帮我配基础开发环境：
1. 使用 Vite 初始化 React+TS 项目
2. 创建 vitest.config.ts，使用 jsdom 环境
3. 创建 vitest.setup.ts，导入 @testing-library/jest-dom
4. 确保组件测试可以在浏览器外运行

2.3 第三步：添加 Cursor 配置​

目标：建立 AI 协作的行为约束

具体操作：

配置 .cursorignore 文件​

示例提示词：

请根据官方与社区常见规范，生成一份 .cursorignore 文件。
要求：
- 排除构建产物、依赖目录（如 node_modules、dist、build 等）
- 排除临时文件、日志、系统文件（如 *.log、*.tmp、.DS_Store）
- 排除测试覆盖率报告（如 coverage、.nyc_output）
- 排除敏感文件（如 .env*、*.pem、*.key）
- 包含常见前端/后端项目的约定忽略项

创建通用开发规则​

示例提示词：

创建 .cursor/rules/index.mdc 通用开发规则：

---
alwaysApply: true
---

# 技术栈约束

- TypeScript 严格模式，React 18 + Vite
- 函数式组件 + Hooks，避免类组件
- 测试使用 Vitest + @testing-library/react
- 文件命名：kebab-case，组件用 PascalCase.tsx

确保 AI 在所有开发中遵循这些约束

创建测试专用规则​

示例提示词：

创建 .cursor/rules/testing.mdc 测试规则：
---
globs: **/*.test.tsx, **/__tests__/**
---

# 测试约定

- 优先 TDD：先写失败测试，再实现功能
- 覆盖：正常路径、边界条件、异常输入
- 循环：执行 npm test，失败时自动修复

自动应用到测试相关文件

2.4 第四步：启用自动化工作流​

目标：配置 Cursor Agent 自动运行测试和构建

具体操作：

配置路径：Cursor → Settings → Agents → Auto-Run Mode(版本 2.0.43，不同版本可能会有差异)

在 Cursor 设置中配置 Auto-Run Mode 为 "Use Allowlist"，并设置命令白名单：

• 允许：npm test、npm run build、npm run dev、npm run lint
• 禁止：rm、git push、npm publish 等危险命令

安全实践：

• 在开启自动运行前先提交代码（git commit）
• 限制 AI 权限在安全命令范围内
• 不授予生产环境凭证的写权限

2.5 第五步：TDD 红-绿-重构循环开发​

目标：在自动化环境下遵循 TDD 最佳实践，逐个组件进行红-绿-重构循环

TDD 循环说明：

• 🔴 红：写一个失败的测试
• 🟢 绿：写最少代码让测试通过
• 🔵 重构：在保持测试通过的前提下优化代码（可选）

重构完成后的下一步：

1. 验证测试通过：确保所有现有测试仍然通过，重构没有破坏功能
2. 评估覆盖度：检查是否需要补充边界条件或异常情况的测试
3. 开始新循环：
   • 如果当前组件功能完整，进入下一个组件的红-绿-重构循环
   • 如果需要新功能，为新功能编写失败测试，开始新的 TDD 循环
4. 集成验证：定期运行完整测试套件，确保各组件协同工作正常

TodoItem 组件 TDD 循环​

• 红阶段 - 写失败测试

  示例提示词：

  创建 src/components/__tests__/todo-item.test.tsx：
  
  测试用例：
  1. 渲染文本与初始完成状态
  2. 勾选触发 onToggle(id, next)
  3. 点击删除触发 onDelete(id)
  
  Todo 模型：{ id: string, text: string, completed: boolean, createdAt: string }
  使用 Vitest + Testing Library，包含 vi.fn() mock
  

• 绿阶段 - 最小实现

  示例提示词：

  实现 src/components/todo-item.tsx，仅满足测试通过：
  @Files src/components/__tests__/todo-item.test.tsx
  
  最小实现要求：
  1. 接收 todo、onToggle、onDelete props
  2. 复选框绑定 completed 状态
  3. 删除按钮触发 onDelete
  
  AI 将自动运行 npm test 确保测试通过（绿）
  

• 重构阶段 - 优化代码

  示例提示词：

  重构 TodoItem 组件，保持测试通过：
  1. 优化组件结构和可读性
  2. 改进无障碍访问性
  3. 优化样式和用户体验
  
  AI 将在每次修改后自动运行 npm test 确保测试仍然通过
  

TodoEditor 组件 TDD 循环​

• 红阶段 - 写失败测试

  示例提示词：

  创建 src/components/__tests__/todo-editor.test.tsx：
  1. 受控输入：输入文本后 value 更新
  2. 空值禁用：空字符串时提交按钮禁用
  3. 提交清空：提交后触发 onAdd({text}) 并清空输入框
  4. 键盘支持：回车键提交
  
  

• 绿阶段 - 最小实现

  示例提示词：

  实现 src/components/todo-editor.tsx 最小功能：
  @Files src/components/__tests__/todo-editor.test.tsx
  
  基本功能：
  1. 受控文本输入框
  2. 空值时禁用提交按钮
  3. 提交时调用 onAdd({text}) 并清空
  4. 支持回车键提交
  
  运行 npm test 确保测试通过（绿）
  

• 重构阶段 - 优化代码

  示例提示词：

  重构 TodoEditor 组件：
  1. 优化表单验证逻辑
  2. 添加适当的 loading 状态
  
  保持测试通过的前提下进行优化
  

App 组件 TDD 循环​

• 红阶段 - 写失败测试

  示例提示词：

  创建 src/app/__tests__/app.integration.test 集成测试：
  1. 页面加载：从 localStorage 读取数据
  2. 完整流程：添加 → 切换完成 → 筛选 → 删除
  3. 数据持久化：操作后 localStorage 更新
  
  使用 jsdom 模拟 localStorage
  

• 绿阶段 - 最小实现

  示例提示词：

  实现 src/app/app.tsx 基本功能：
  @Files src/app/__tests__/app.test.tsx
  
  核心功能：
  1. localStorage 数据持久化（key: 'todo-app:v1'）
  2. 基本状态管理：todos、filter
  3. 事件处理：onAdd、onToggle、onDelete
  4. 简单筛选逻辑：all/active/completed
  
  运行 npm test 确保测试通过（绿）
  

• 重构阶段 - 优化架构

  示例提示词：

  重构 App 组件架构：
  1. 提取状态管理逻辑（useReducer 或自定义 hooks）
  2. 改进错误处理和边界情况
  3. 添加按创建时间排序等高级功能
  
  每次重构后自动确保所有测试通过
  

2.6 第六步：配置 CI/CD 流水线​

目标：建立自动化测试和部署流程

具体操作：

创建 GitHub Actions​

示例提示词：

生成 .github/workflows/ci.yml 工作流：
1. 触发条件：push 和 PR 到 master 分支
2. 环境：Node.js 20
3. 步骤：checkout → install → build → test → coverage
4. 失败时阻止合并

配置部署流程​

示例提示词：

创建 Vercel 部署配置：
1. 生成 vercel.json 配置文件
2. 设置构建命令和输出目录
3. 配置环境变量和重定向规则

2.7 第七步：完善文档和验收​

目标：生成完整的项目文档和验收测试

具体操作：

生成项目文档​

示例提示词：

更新 README.md 包含：
1. 项目介绍和功能特性
2. 技术栈和架构说明
3. 本地开发指南（安装、运行、测试）
4. 部署链接和演示
5. 贡献指南和许可证

创建验收测试清单​

示例提示词：

创建 ACCEPTANCE.md 验收清单：
1. 功能测试：所有用户故事验证通过
2. 技术测试：测试覆盖率 > 80%，构建成功
3. 用户体验：响应式设计，无障碍访问
4. 性能测试：首屏加载 < 2s

总结​

Cursor 最佳实践的核心在于建立系统化的 AI 协作流程，通过以下关键要素实现高效开发：

核心原则​

1. TDD 驱动迭代：以测试为先导，相比于人工开发中“先实现再测试”的习惯，TDD 在 AI 辅助下更具价值， 它能作为清晰的反馈循环与安全护栏，帮助 AI 保持正确的开发方向。
2. 结构化配置：通过 PRD 规划、规则文件、上下文标签等，为 AI 提供明确的行为约束和项目背景
3. 自动化反馈：利用 Auto-Run 模式建立快速验证机制，实现"红-绿-重构"的高效循环

适用范围​

这套最佳实践不仅适用于 Cursor，也可推广到其他 AI 编程助手（如 Trae、GitHub Copilot 等），只需根据具体工具的配置方式进行调整。关键在于理解 AI 协作的本质：通过结构化输入和反馈循环，让 AI 成为更可靠的编程伙伴。

参考资料​

• Cursor 官方文档
• Mastering Cursor IDE: 10 Best Practices Building a Daily Task Manager App (Medium)
• Cursor Best Practices (GitHub)
• Cursor IDE 规则与 AI 协作（Kirill Markin 博客）
• Cursor Prompt Engineering 最佳实践（官方论坛）
• Cursor Tips（Builder.io 博客）
• 中大型项目最佳实践（官方论坛）
• Mastering Cursor IDE: Thinking Models, Cursor Rules and Effective Usage (Medium)
• Cursor IDE Setup and Workflow in Larger Projects（Reddit）
• Cursor Tips（dev.to）

1. 核心原理​

1.1 LaunchDaemon vs LaunchAgent​

macOS 提供两种自动启动机制：

Jenkins Agent 应使用 LaunchDaemon 以确保服务稳定运行且不受用户会话影响。

1.2 防休眠机制​

使用 caffeinate 命令包裹 Jenkins Agent 进程，防止系统休眠导致网络断开：

caffeinate -s java -jar agent.jar [options]

参数说明：

• -s: 防止系统休眠（但允许屏幕息屏）
• 进程存活期间持续生效

2. 前置要求​

1. Java 环境：已安装 JDK（Jenkins Agent 需要）
2. Jenkins 凭据：从 Jenkins Master 获取 Agent 连接信息
3. 管理员权限：配置 LaunchDaemon 需要 sudo 权限
4. 工作目录：准备 Jenkins 工作目录（如 /Users/xhm/jenkins）

3. 配置步骤​

3.1 第一步：创建 Plist 配置文件​

创建 org.jenkins.agent.plist 文件（建议先在用户目录创建，测试后再移动）：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- 服务唯一标识 -->
    <key>Label</key>
    <string>org.jenkins.agent</string>

    <!-- 使用 caffeinate 防休眠 -->
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/caffeinate</string>
        <string>-s</string>
        <string>/usr/bin/java</string>
        <string>-jar</string>
        <string>/Users/xhm/jenkins/agent.jar</string>
        <string>-url</string>
        <string>http://your-jenkins-server:8080/</string>
        <string>-secret</string>
        <string>YOUR_SECRET_KEY</string>
        <string>-name</string>
        <string>YOUR_AGENT_NAME</string>
        <string>-workDir</string>
        <string>/Users/xhm/jenkins</string>
    </array>

    <!-- 运行用户（保持与文件所有者一致）-->
    <key>UserName</key>
    <string>xhm</string>

    <!-- 工作目录 -->
    <key>WorkingDirectory</key>
    <string>/Users/xhm/jenkins</string>

    <!-- 自动启动 -->
    <key>RunAtLoad</key>
    <true/>

    <!-- 崩溃后自动重启 -->
    <key>KeepAlive</key>
    <true/>

    <!-- 标准输出日志 -->
    <key>StandardOutPath</key>
    <string>/Users/xhm/jenkins/jenkins-agent.log</string>

    <!-- 错误输出日志 -->
    <key>StandardErrorPath</key>
    <string>/Users/xhm/jenkins/jenkins-agent-error.log</string>

    <!-- 环境变量（可选）-->
    <key>EnvironmentVariables</key>
    <dict>
        <key>JAVA_HOME</key>
        <string>/path/to/your/jdk</string>
    </dict>
</dict>
</plist>

3.2 第二步：部署配置文件​

将配置文件复制到系统目录并设置正确的权限：

# 复制配置文件到系统目录
sudo cp ~/org.jenkins.agent.plist /Library/LaunchDaemons/

# 设置文件所有者和所属组
sudo chown root:wheel /Library/LaunchDaemons/org.jenkins.agent.plist

# 设置文件权限
sudo chmod 644 /Library/LaunchDaemons/org.jenkins.agent.plist

权限配置详解​

1. 设置所有者和组（chown）

sudo chown root:wheel /Library/LaunchDaemons/org.jenkins.agent.plist

• 作用：将文件的所有者改为 root，所属组改为 wheel
• 含义：
  • root 是系统超级用户，拥有最高权限
  • wheel 是 macOS 中传统的管理员组（继承自 Unix 系统）
• 为什么需要：系统级 LaunchDaemons 必须由 root 拥有，以确保安全性和系统启动时的可靠加载

2. 设置文件权限（chmod）

sudo chmod 644 /Library/LaunchDaemons/org.jenkins.agent.plist

• 作用：设置文件的权限模式为 644
• 权限分解：
  • 6 (所有者 root): 读(4) + 写(2) = 6 → 可读写
  • 4 (组 wheel): 只读(4) → 仅可读
  • 4 (其他用户): 只读(4) → 仅可读
• 为什么需要：
  • launchd 需要读取这些文件来管理服务
  • 普通用户不应能修改系统服务配置，防止安全风险
  • 遵循最小权限原则，是 macOS 系统服务的标准配置方式

3.3 第三步：加载并启动服务​

# 加载服务
sudo launchctl load /Library/LaunchDaemons/org.jenkins.agent.plist

# 验证服务状态
launchctl list | grep jenkins

3.4 第四步：验证运行状态​

# 查看服务列表
launchctl list | grep org.jenkins.agent

# 查看日志
tail -f /Users/xhm/jenkins/jenkins-agent.log

# 确认 caffeinate 进程存在
ps aux | grep caffeinate | grep jenkins

4. 服务管理​

4.1 常用命令​

# 停止服务
sudo launchctl unload /Library/LaunchDaemons/org.jenkins.agent.plist

# 启动服务
sudo launchctl load /Library/LaunchDaemons/org.jenkins.agent.plist

# 重启服务（先停止再启动）
sudo launchctl unload /Library/LaunchDaemons/org.jenkins.agent.plist
sudo launchctl load /Library/LaunchDaemons/org.jenkins.agent.plist

# 查看服务状态
launchctl list | grep jenkins

# 查看实时日志
tail -f /Users/xhm/jenkins/jenkins-agent.log

# 查看错误日志
tail -f /Users/xhm/jenkins/jenkins-agent-error.log

4.2 常见问题​

4.2.1 息屏后仍然断开​

检查清单：

1. 确认使用了 caffeinate：

   ps aux | grep caffeinate | grep jenkins
   

2. 检查网络配置（防止 Wi-Fi 休眠）：

   • 系统偏好设置 → 电池 → 电源适配器
   • 取消勾选"当显示器关闭时，防止电脑自动进入睡眠"

3. 验证 caffeinate 参数：

   # 确保配置中使用了 -s 参数
   grep -A10 ProgramArguments /Library/LaunchDaemons/org.jenkins.agent.plist
   

4.2.2 权限问题​

症状：日志文件无法写入或工作目录访问失败

解决方法：

# 确保工作目录存在且有正确权限
mkdir -p /Users/xhm/jenkins
chown xhm:staff /Users/xhm/jenkins
chmod 755 /Users/xhm/jenkins

# 确保日志文件可写
touch /Users/xhm/jenkins/jenkins-agent.log
chown xhm:staff /Users/xhm/jenkins/jenkins-agent.log

5. 参考资源​

• Apple LaunchDaemon 官方文档
• caffeinate 命令手册
• Jenkins Agent 配置指南

1. 前置条件​

• Linux 系统（支持 systemd）
• sudo 权限
• 网络连接（用于下载 Java）
• Jenkins 服务端的 URL 和 Secret

2. 安装步骤​

2.1 步骤 1: 安装 Java 17​

Jenkins Agent 需要 Java 17 或更高版本。检查系统中的 Java 版本：

java -version

如果系统没有 Java 或版本低于 17，需要安装 Java 17。

方法 1: 从 Adoptium 下载安装（推荐）​

# 创建临时目录
cd ~
mkdir -p java-install
cd java-install

# 下载 OpenJDK 17
wget https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.10%2B7/OpenJDK17U-jdk_x64_linux_hotspot_17.0.10_7.tar.gz

# 解压
tar -xzf OpenJDK17U-jdk_x64_linux_hotspot_17.0.10_7.tar.gz

# 安装到系统目录
sudo mv jdk-17.0.10+7 /usr/local/jdk-17

# 验证安装
/usr/local/jdk-17/bin/java -version

2.2 步骤 2: 准备 Agent 文件​

1. 创建工作目录

mkdir -p /home/xhm/jenkins
cd /home/xhm/jenkins

1. 下载 agent.jar

从 Jenkins 服务端下载 agent.jar 文件，或使用已有的 agent.jar，确保文件位于：

/home/xhm/jenkins/agent.jar

2.3 步骤 3: 创建服务文件​

创建 systemd 服务文件 /home/xhm/jenkins/jenkins-agent.service：

sudo nano /home/xhm/jenkins/jenkins-agent.service

服务文件内容如下（请根据实际情况修改相关参数）：

[Unit]
Description=Jenkins Agent Service
After=network.target
Wants=network.target

[Service]
Type=simple
User=xhm
Group=xhm
WorkingDirectory=/home/xhm/jenkins
ExecStart=/usr/local/jdk-17/bin/java -jar /home/xhm/jenkins/agent.jar -url http://192.168.20.35:11080/ -secret 9e96e61eba4156e1076d77375aaefde46f99721cec6dcdsafascddaa8091d721b05 -name "linux-agent" -webSocket -workDir "/home/xhm/jenkins"
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=jenkins-agent

# Environment variables (if needed)
Environment=JAVA_HOME=/usr/local/jdk-17
Environment=PATH=/usr/local/jdk-17/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/xhm/jenkins

[Install]
WantedBy=multi-user.target

配置说明​

服务文件参数详解​

Agent 参数说明​

安全设置​

服务文件中包含以下安全设置：

• NoNewPrivileges=true: 禁止获取新权限
• PrivateTmp=true: 使用私有临时目录
• ProtectSystem=strict: 保护系统目录
• ProtectHome=read-only: 保护家目录为只读
• ReadWritePaths: 指定可写路径

2.4 步骤 4: 安装并启用服务​

1. 复制服务文件到 systemd 目录

sudo cp /home/xhm/jenkins/jenkins-agent.service /etc/systemd/system/

1. 重新加载 systemd 配置

sudo systemctl daemon-reload

1. 启用开机自启动

sudo systemctl enable jenkins-agent.service

1. 启动服务

sudo systemctl start jenkins-agent.service

2.5 步骤 5: 验证服务​

1. 检查服务状态

sudo systemctl status jenkins-agent

正常运行的输出应该显示：

● jenkins-agent.service - Jenkins Agent Service
   Loaded: loaded (/etc/systemd/system/jenkins-agent.service; enabled)
   Active: active (running) since ...

1. 查看服务日志

# 查看实时日志
sudo journalctl -u jenkins-agent -f

# 查看最近50条日志
sudo journalctl -u jenkins-agent -n 50

# 查看今天的日志
sudo journalctl -u jenkins-agent --since today

3. 服务管理​

3.1 常用命令​

# 启动服务
sudo systemctl start jenkins-agent

# 停止服务
sudo systemctl stop jenkins-agent

# 重启服务
sudo systemctl restart jenkins-agent

# 查看服务状态
sudo systemctl status jenkins-agent

# 查看服务日志
sudo journalctl -u jenkins-agent -f

# 启用开机自启动
sudo systemctl enable jenkins-agent

# 禁用开机自启动
sudo systemctl disable jenkins-agent

# 检查服务是否开机自启
sudo systemctl is-enabled jenkins-agent

3.2 服务自动重启​

服务配置中已设置 Restart=always，当服务异常退出时会在 10 秒后自动重启。

4. 故障排查​

4.1 问题 1: 服务无法启动​

症状: systemctl status 显示 failed 或 inactive (dead)

排查步骤:

1. 查看详细日志：

   sudo journalctl -u jenkins-agent -n 100 --no-pager
   

2. 检查 Java 路径是否正确：

   ls -la /usr/local/jdk-17/bin/java
   

3. 检查 agent.jar 是否存在：

   ls -la /home/xhm/jenkins/agent.jar
   

4. 检查工作目录权限：

   ls -ld /home/xhm/jenkins
   

4.2 问题 2: Java 版本不匹配​

症状: 日志中出现 UnsupportedClassVersionError

错误示例:

java.lang.UnsupportedClassVersionError: class file version 61.0 ...
this version of the Java Runtime only recognizes class file versions up to 55.0

解决方案:

• class file version 61.0 表示需要 Java 17
• 55.0 表示当前 Java 版本是 11
• 需要安装 Java 17 或更高版本（参考步骤 1）

4.3 问题 3: 无法连接到 Jenkins​

症状: 日志中显示连接失败

排查步骤:

1. 检查网络连接：

   ping 192.168.20.35
   curl -I http://192.168.20.35:18080/
   

2. 验证 URL 和 Secret 是否正确

3. 检查防火墙设置：

   sudo ufw status
   

4. 查看详细错误信息：

   sudo journalctl -u jenkins-agent -f
   

4.4 问题 4: 权限问题​

症状: 日志中显示 Permission denied

解决方案:

1. 检查文件所有权：

   sudo chown -R xhm:xhm /home/xhm/jenkins
   

2. 检查文件权限：

   chmod 644 /home/xhm/jenkins/agent.jar
   

4.5 问题 5: 服务频繁重启​

症状: 服务状态显示 activating (auto-restart)

排查步骤:

1. 查看详细错误日志
2. 检查 Java 路径和 agent.jar 路径是否正确
3. 检查工作目录是否可写
4. 检查 Jenkins 服务端是否可访问

5. 总结​

完成以上步骤后，Jenkins Agent 已配置为系统服务，具备以下特性：

✅ 开机自动启动 ✅ 服务异常时自动重启 ✅ 日志记录到 systemd journal ✅ 安全配置限制权限 ✅ 易于管理和监控

如遇到问题，请参考故障排查章节或查看详细日志。

1. 概念介绍​

1.1 Cursor 规则概述​

Cursor 规则是一个分层的配置系统，用于指导 AI 助手在代码生成、建议和分析过程中的行为。它由两个互补的层级组成：

• 用户规则（User Rules）：存储在 Cursor 设置中的全局规则，适用于所有项目
• 项目规则（Project Rules）：存储在项目 .cursor/rules/ 目录中的特定规则，仅适用于当前项目

1.2 规则的核心作用​

规则系统主要解决四个问题：

1. 保持一致 - AI 按统一标准工作，代码风格统一
2. 个性定制 - 适应你的习惯和项目需求
3. 提升质量 - 减少错误，自动应用最佳实践
4. 提高效率 - 减少重复说明，AI 更准确

1.3 规则优先级体系​

项目规则 > 用户规则 > 默认行为

这种设计确保了灵活性：用户规则提供一致的个人偏好基线，项目规则可以根据特定需求进行覆盖和补充。

2. 规则配置详解​

2.1 用户规则格式​

存储位置：Cursor Settings → Rules & Memories → User Rules(不同版本可能有差异)

用户规则特性：

2.2 项目规则格式（MDC）​

存储位置：项目根目录 .cursor/rules/*.mdc

格式：MDC（Markdown with Components）

作用范围：当前项目

MDC 文件结构：

---
description: "规则的简短描述"
globs: **/*.ts,**/*.tsx
alwaysApply: true
---

# 规则标题

规则的具体内容...

2.3 MDC 元数据字段详解​

2.4 规则应用模式​

Cursor 提供四种规则应用模式，满足不同场景的需求：

模式 1：Always Apply（总是应用）​

配置方式：

---
alwaysApply: true
---

特点：

• 在所有对话、编辑、补全中自动应用
• 适用于全局性的规范要求

适用场景：

• 安全规范（如禁止硬编码密钥）
• 代码格式要求（如缩进、命名规范）
• 错误处理标准

模式 2：Apply Intelligently（智能应用）​

配置方式：

---
description: "React Hooks 使用规范"
---

特点：

• AI 根据 description 和上下文智能判断是否应用
• 无需手动指定文件模式
• 灵活性强，减少配置复杂度

适用场景：

• 特定技术栈的最佳实践（AI 可判断何时相关）
• 业务领域规范（如"支付模块必须有事务处理"）
• 复杂的条件性规则

模式 3：Apply to Specific Files（应用到特定文件）​

配置方式：

---
description: "TypeScript 类型定义规范"
globs: **/*.ts,**/*.tsx
---

特点：

• 精确控制规则应用范围
• 基于文件路径模式匹配

适用场景：

• 特定文件类型的规则（如测试文件、配置文件）
• 特定目录的规则（如组件目录、工具目录）
• 需要精确控制作用范围的规则

示例：

# 匹配特定文件类型
globs: **/*.ts,**/*.tsx

# 匹配特定目录
globs: src/components/**/*

# 匹配测试文件
globs: **/*.test.ts,**/*.spec.ts,**/__tests__/**

# 匹配多种文件类型和目录
globs: **/*.js,**/*.jsx,src/utils/**/*,src/hooks/**/*

Globs 生效时机：

当你打开、编辑文件或使用 AI 补全/Chat 时，Cursor 会根据当前文件路径匹配相应的规则。

匹配机制示例：

• 编辑 src/components/Button.tsx 时，会应用所有匹配该路径的规则
• 例如：**/*.tsx（匹配所有 TypeScript React 文件）、src/components/**/*（匹配组件目录下所有文件）

Globs 匹配机制确保了不同类型的文件能够应用最适合的规则配置。

模式 4：Apply Manually（手动应用）​

配置方式：

创建规则文件（如 legacy-code.mdc），不设置 alwaysApply 或 globs

使用方式：

在对话中通过 @ 符号手动引用：

@legacy-code 帮我重构这段代码

特点：

• 完全由用户控制何时应用
• 不会自动触发
• 可作为临时规则或特殊场景规则

适用场景：

• 遗留代码重构指导
• 特殊的一次性任务规则
• 实验性规范

2.5 规则管理与调试​

切换规则类型​

在 Cursor 中打开规则文件后，通过顶部的类型下拉菜单选择规则类型，该操作会自动更新 description、globs 和 alwaysApply 属性。

查看已启用的规则​

已启用的规则会显示在 Agent 对话框的上下文管理栏（顶部），如下图所示：

如上图所示，编号 2 处展示了激活的两条规则（一条为 alwaysApply: true 的全局应用规则，另一条为通过 globs 匹配到当前文件的规则）。tab 指示的是你正在编辑的文件。

排查规则问题​

如果规则没生效，可以在规则设置中看到错误信息，如下图：

3. 最佳实践​

3.1 规则编写技巧​

具体明确，避免模糊​

不好的规则：
- "代码要写得好"
- "保持良好的代码风格"
- "注意性能优化"

好的规则：
- "使用 2 空格缩进，不使用 Tab"
- "函数命名使用驼峰命名法，类使用 PascalCase"
- "列表渲染超过 100 项时使用虚拟滚动"

分层设计规则​

通用规则（alwaysApply: true）：
- 安全规范
- 错误处理
- 代码格式

特定规则（globs:xx）：
- 特定框架约定（React、Vue）
- 特定文件类型（测试、配置）
- 特定业务场景

3.2 规则文件组织​

推荐的目录结构​

.cursor/rules/
├── README.md              # 规则文档说明
├── core/                  # 核心规则（alwaysApply: true）
│   ├── security.mdc       # 安全规范
│   ├── errors.mdc         # 错误处理
│   └── format.mdc         # 代码格式
├── languages/             # 语言特定规则
│   ├── typescript.mdc
│   └── python.mdc
├── frameworks/            # 框架规则
│   └── react.mdc
└── project-specific/      # 项目特定规则
    ├── api.mdc
    └── database.mdc

3.3 版本控制与团队协作​

规则文件纳入版本控制​

.gitignore 中不要忽略 .cursor 目录

4. 实用示例​

4.1 用户规则示例​

用户规则采用纯文本格式，在 Cursor 设置中配置，适用于所有项目：

1. 语言与注释
- 默认使用中文回答问题，除非用户特别要求英文
- 默认使用英文代码注释，除非特别要求中文
- 公共 API 使用 JSDoc/TSDoc 格式

2. 回答风格
- 尽量简洁明了，避免不必要的废话和重复说明
- 先给出关键答案，再提供简短解释或示例

3. 安全与稳健性（最高优先级）
- 绝对禁止硬编码任何敏感信息（密码、API密钥、IP）
- 所有配置必须从环境变量或配置文件中读取
- 必须进行错误处理，对可能失败的操作使用 try-catch 或等效机制

4. 代码整洁与可维护性（参考《代码整洁之道》）
- 函数短小且单一职责，每个函数只做一件事
- 变量、函数、类命名语义清晰，易读易理解
- 避免重复代码（遵循 DRY 原则）
- 错误处理明确且一致，保证程序健壮
- 模块和类职责明确，依赖清晰，便于扩展和维护

5. 设计模式规范
- 优先使用常见设计模式优化结构与扩展性。
- 推荐使用的设计模式：
  - 单例模式（Singleton）：用于全局唯一实例。
  - 工厂方法模式（Factory Method）：避免直接实例化，提升可扩展性。
  - 策略模式（Strategy）：将可变行为封装为可替换策略。
  - 观察者模式（Observer）：用于事件驱动和响应式设计。
  - 装饰器模式（Decorator）：在不修改原类的情况下动态扩展功能。
  - 命令模式（Command）：将操作封装为对象，便于撤销与队列化。
  - 适配器模式（Adapter）：用于兼容不同接口的组件。按这个格式修改
  - Proxy（代理模式）：控制访问或增强功能（缓存、安全、远程访问）

4.2 项目规则示例​

项目规则采用 MDC 格式，存储在 .cursor/rules/ 目录中，仅适用于当前项目。以下展示不同应用模式的实际使用场景：

示例 1：Always Apply - 安全规范​

.cursor/rules/core/security.mdc：

---
description: "全局安全规范，所有代码必须遵守"
alwaysApply: true
---

# 安全规范

## 敏感信息处理

- 绝对禁止硬编码任何敏感信息（密码、API密钥、IP地址、Token）
- 所有配置必须从环境变量或加密配置文件中读取
- 使用 `.env.example` 提供配置模板，真实配置文件加入 `.gitignore`

## 数据验证

- 所有用户输入必须进行验证和清理
- API 请求参数必须进行类型检查和范围验证
- 数据库查询使用参数化查询，防止 SQL 注入

示例 2：Apply Intelligently - 框架最佳实践​

.cursor/rules/frameworks/react-hooks.mdc：

---
description: "React Hooks 使用规范和最佳实践"
---

# React Hooks 规范

AI 会在检测到 React Hooks 相关代码时自动应用此规则。

## Hooks 使用规则

- 只在 React 函数组件或自定义 Hooks 中调用 Hooks
- 不在循环、条件或嵌套函数中调用 Hooks
- 自定义 Hook 必须以 `use` 开头命名

## 依赖数组规范

- useEffect/useMemo/useCallback 必须正确声明依赖项
- 避免遗漏依赖导致的过期闭包问题
- 对象和函数依赖应该用 useMemo/useCallback 包装

示例 3：Apply to Specific Files - TypeScript 类型规范​

.cursor/rules/languages/typescript.mdc：

---
description: "TypeScript 类型定义和使用规范"
globs: **/*.ts,**/*.tsx
---

# TypeScript 规范

## 类型定义

- Props 接口使用 `interface` 定义并导出
- 工具类型使用 `type` 定义
- 避免使用 `any`，优先使用具体类型或泛型
- 使用 `unknown` 替代 `any` 处理不确定类型

## 组件类型

- React 组件 Props 必须有完整的类型定义
- 函数组件使用 `React.FC` 或显式声明返回类型
- 事件处理函数使用正确的事件类型（如 `React.ChangeEvent<HTMLInputElement>`）

示例 4：Apply Manually - 遗留代码处理​

.cursor/rules/project-specific/legacy-refactor.mdc：

---
description: "遗留代码重构指南，需手动引用"
---

# 遗留代码重构指南

通过 @legacy-refactor 手动引用此规则

## 重构策略

- 保持原有功能不变，先添加测试用例
- 逐步替换旧 API，保持向后兼容
- 使用适配器模式过渡新旧实现
- 重构完成后更新文档和注释

## 临时豁免

遗留代码重构期间允许：
- 使用 `@ts-ignore` 标记已知类型问题
- 保留部分 `any` 类型（需添加 TODO 注释）
- 暂不强制执行最新的代码规范

总结：

有效的 Cursor 规则体系需要持续迭代和优化。从简单的个人偏好开始，逐步构建团队共享的规则库，结合版本控制和团队协作流程，最终形成提升开发效率和代码质量的强大工具。

1. 什么是 ABI？​

ABI 是一种接口规范，它定义了程序在二进制层面的交互规则：

这些规则决定了编译后的程序能否在不同系统上正确运行。

1.1 举个例子​

假设你写了一个简单函数：

int add(int a, int b) {
    return a + b;
}

当你将其编译成 .so 动态库供 Python 调用时，Python 需要知道：

• 参数 a 和 b 应该放在哪里？
• 返回值从哪里获取？
• 数据结构如何对齐和布局？
• 函数在库中的实际名称是什么？

这一切都由 ABI 规范决定。

1.2 形象比喻：ABI 就像快递包装标准​

想象两个快递公司需要合作，一个负责发货，一个负责收货。

ABI 就像是规定快递如何打包、寄送地址、标签位置、地址语言的包装手册。

如果不遵守包装标准会怎样？ 快递丢失、无法打开、地址错误、仓库爆满 —— 这和 ABI 不一致时的二进制兼容性错误完全一样！

2. glibc 与 ABI 的关系​

glibc 是 Linux 系统中 ABI 规范的核心实现之一。

2.1 什么是 glibc？​

glibc（GNU C Library）是：

• Linux 上最常用的 C 标准库实现
• 提供核心函数：malloc()、printf()、fork()、pthread_create() 等
• 应用程序与 Linux 系统调用之间的桥梁
• 系统调用的封装层
• ABI 规范的具体实现载体

2.2 glibc 与 ABI 的关系​

2.3 实际案例​

创建一个简单程序 hello.cpp：

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

int main() {
    printf("Hello\n");              // GLIBC_2.2.5
    malloc(100);                    // GLIBC_2.2.5

    // 使用较新的函数
    memcpy(dest, src, 100);         // GLIBC_2.14 (2011年优化版本)
    reallocarray(ptr, 10, 20);      // GLIBC_2.27 (2018年新增)

    return 0;
}

在 Ubuntu 22.04（glibc 2.35）上编译后，查看依赖的 glibc 版本：

readelf -s ./a.out | grep GLIBC_

输出结果：

printf@GLIBC_2.2.5
malloc@GLIBC_2.2.5
memcpy@GLIBC_2.14
reallocarray@GLIBC_2.27

3. 跨系统兼容性解决方案​

如果希望程序能在多个不同的 Linux 系统上运行（Ubuntu 20.04、Debian 10、CentOS 7 等），就必须考虑 ABI 兼容性。

3.1 基本原则：向后兼容​

在较旧版本的 Linux 系统上编译程序，这样生成的二进制文件才能在较新系统上运行（向前兼容）。

兼容性示例​

正确做法：

• 在 CentOS 7（glibc 2.17）上编译 Qt5 应用
• 可以运行在：CentOS 7、Ubuntu 20.04、Ubuntu 22.04

错误做法：

• 在 Ubuntu 22.04（glibc 2.35）上编译应用
• 只能运行在：Ubuntu 22.04
• 无法运行在：CentOS 7（glibc 版本太旧，找不到符号）

3.2 解决方案​

方案一：在旧系统上构建​

方案二：现代打包格式​

4. 总结​

ABI 是程序在"机器语言"层面交流的规则手册，就像快递行业的包装标准，确保每个程序都能正确发货、收货、协作和运行。

glibc 作为 ABI 的具体实现，其版本兼容性直接影响程序的跨系统运行能力。

1. CMakeLists.txt - 项目构建规则​

CMakeLists.txt 是 CMake 项目的核心配置文件，定义项目构建规则和目标。

# 基本项目配置
cmake_minimum_required(VERSION 3.16)
project(MyProject VERSION 1.0.0 LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)

# 目标定义
add_executable(myapp src/main.cpp)
add_library(mylib STATIC src/lib.cpp)

# 目标配置
target_include_directories(myapp PRIVATE include)
target_link_libraries(myapp PRIVATE mylib)

# 编译选项
if(MSVC)
    target_compile_options(myapp PRIVATE /W4)
else()
    target_compile_options(myapp PRIVATE -Wall -Wextra)
endif()

2. toolchain.cmake - 工具链/交叉编译​

工具链文件定义编译器和构建工具配置，用于交叉编译（在一台电脑上编译，但编译出来的程序是给另一种架构/系统 运行的）。toolchain.cmake 本质上还是一个 普通的 CMake 脚本文件，只是内容和用途不同。

# toolchain.cmake - 简单的ARM交叉编译配置-x86 PC 上用这个配置编译出在 ARM Linux 上能运行的程序
# 告诉 CMake 目标系统是 Linux，不是宿主机的系统。
set(CMAKE_SYSTEM_NAME Linux)

#告诉 CMake 目标 CPU 架构是 ARM
set(CMAKE_SYSTEM_PROCESSOR arm)

# 设置交叉编译器
# 指定 C 语言编译器，用交叉编译器arm-linux-gnueabihf-gcc而不是本地 gcc。
set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc)
# 指定 C++ 编译器，同样是交叉编译器 arm-linux-gnueabihf-g++
set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++)

# 设置查找路径
set(CMAKE_FIND_ROOT_PATH /usr/arm-linux-gnueabihf)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)

使用方法：

cmake -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake ..

3. CMakeCache.txt - 缓存配置​

CMakeCache.txt 是 CMake 自动生成的文件，位于你的 build 目录下（比如 build/CMakeCache.txt）。它存储了配置阶段的所有缓存变量，包括编译器路径、编译选项、自定义缓存变量等。CMake 下次配置时会直接读取这个文件，加快配置速度，并保留用户手动修改的变量。

缓存变量管理​

# 设置缓存变量
set(BUILD_TYPE "Release" CACHE STRING "Build configuration type")
set(ENABLE_TESTING ON CACHE BOOL "Enable unit testing")
set(INSTALL_PREFIX "/usr/local" CACHE PATH "Installation directory")

# 缓存变量选项
set_property(CACHE BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "MinSizeRel" "RelWithDebInfo")

# 强制缓存变量
set(FORCE_REBUILD OFF CACHE BOOL "Force complete rebuild" FORCE)

缓存操作命令​

# 查看缓存内容
cmake -L

# 查看高级缓存选项
cmake -LA

# 清除缓存
rm CMakeCache.txt
# 或
cmake --build . --target clean

# 修改缓存变量
cmake -DCMAKE_BUILD_TYPE=Debug .

4. FindXXX.cmake / XXXConfig.cmake - 依赖库查找​

这些文件定义了如何查找和配置外部依赖库。

FindXXX.cmake 模块​

FindMyLibrary.cmake 定义了 CMake 如何找到你的库，也就是告诉 find_package(MyLibrary)：

• 去哪些路径找头文件 (.h)
• 去哪些路径找库文件 (.so/.a/.lib)
• 可选地去哪里读取版本信息
• 最后生成 MyLibrary_FOUND 变量和一个现代 CMake target

换句话说，就是在告诉 CMake “如果有人调用 find_package(MyLibrary)，就按我定义的规则去找这个库”。

# FindMyLibrary.cmake
# 查找MyLibrary库的CMake模块

# 查找头文件
find_path(MYLIBRARY_INCLUDE_DIR
    NAMES mylibrary.h
    PATHS
        /usr/include
        /usr/local/include
        ${MYLIBRARY_ROOT}/include
    PATH_SUFFIXES mylibrary
)

# 查找库文件
find_library(MYLIBRARY_LIBRARY
    NAMES mylibrary libmylibrary
    PATHS
        /usr/lib
        /usr/local/lib
        ${MYLIBRARY_ROOT}/lib
    PATH_SUFFIXES x86_64-linux-gnu
)

# 版本检查
if(MYLIBRARY_INCLUDE_DIR)
    file(READ "${MYLIBRARY_INCLUDE_DIR}/mylibrary_version.h" VERSION_FILE)
    string(REGEX MATCH "#define MYLIBRARY_VERSION \"([0-9.]+)\"" _ ${VERSION_FILE})
    set(MYLIBRARY_VERSION ${CMAKE_MATCH_1})
endif()

# 结果处理
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(MyLibrary
    REQUIRED_VARS MYLIBRARY_LIBRARY MYLIBRARY_INCLUDE_DIR
    VERSION_VAR MYLIBRARY_VERSION
)

# 创建导入目标
if(MyLibrary_FOUND AND NOT TARGET MyLibrary::MyLibrary)
    # 创建空target
    add_library(MyLibrary::MyLibrary UNKNOWN IMPORTED)
    # 设置属性，这一步把 target 变得完整，上层 target 才能直接 target_link_libraries 使用它。
    set_target_properties(MyLibrary::MyLibrary PROPERTIES
        IMPORTED_LOCATION "${MYLIBRARY_LIBRARY}"
        INTERFACE_INCLUDE_DIRECTORIES "${MYLIBRARY_INCLUDE_DIR}"
    )
endif()

示例：

find_package(MyLibrary REQUIRED)
target_link_libraries(MyApp PRIVATE MyLibrary::MyLibrary)

XXXConfig.cmake 配置文件​

通俗的讲：FindXXX.cmake → “去哪里找这个库？怎么找？”而 XXXConfig.cmake → “库就在这里，按我给的规则用它就行。”

# MyLibraryConfig.cmake
# 由库提供的配置文件

@PACKAGE_INIT@

# 检查组件
set(_supported_components Core Utils Network)

foreach(_comp ${MyLibrary_FIND_COMPONENTS})
    if(NOT _comp IN_LIST _supported_components)
        set(MyLibrary_FOUND False)
        set(MyLibrary_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
    endif()
endforeach()

# 包含目标文件
# MyLibraryTargets.cmake 包含了库的目标文件和头文件路径，不用像FindMyLibrary.cmake那样去自己搜索
include("${CMAKE_CURRENT_LIST_DIR}/MyLibraryTargets.cmake")

# 版本检查
check_required_components(MyLibrary)

示例：

# 在CMakeLists.txt中使用
find_package(MyLibrary 2.0 REQUIRED COMPONENTS Core Utils)

if(MyLibrary_FOUND)
    target_link_libraries(myapp PRIVATE MyLibrary::MyLibrary)
    message(STATUS "Found MyLibrary version: ${MyLibrary_VERSION}")
endif()

5. CPackConfig.cmake / CTestConfig.cmake - 打包与测试​

这些配置文件用于项目的打包发布和测试管理。

CPackConfig.cmake - 打包配置​

CPackConfig.cmake 和 CMakeLists.txt 在功能上有明确的分工 - CMakeLists.txt 负责项目的构建规则和目标定义，而 CPackConfig.cmake 专注于打包配置和发布相关的设置。虽然这些打包配置技术上可以直接写在 CMakeLists.txt 中，但分离到独立的 CPackConfig.cmake 文件可以让项目结构更清晰，维护更方便。

# CPackConfig.cmake - 简单的打包配置
set(CPACK_PACKAGE_NAME "MyApplication")
set(CPACK_PACKAGE_VERSION "${PROJECT_VERSION}")
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "My awesome application")
set(CPACK_PACKAGE_VENDOR "My Company")

# 设置打包格式
set(CPACK_GENERATOR "TGZ;ZIP")

# 包含CPack
include(CPack)

使用方式：

# 在CMakeLists.txt中引用
include(CPackConfig.cmake)

# 构建并打包
cmake --build build
cpack --config build/CPackConfig.cmake

# 或者直接在构建目录中
cd build
cpack

CTestConfig.cmake - 测试配置​

本质上，CTestConfig.cmake 里的配置完全可以写进普通的 CMakeLists.txt，只是“职责分工”不同：

# CTestConfig.cmake
set(CTEST_PROJECT_NAME "MyProject")
set(CTEST_NIGHTLY_START_TIME "00:00:00 EST")

# 测试超时设置
set(CTEST_TEST_TIMEOUT 300)

# 内存检查
set(CTEST_MEMORYCHECK_COMMAND "valgrind")
set(CTEST_MEMORYCHECK_COMMAND_OPTIONS "--leak-check=full --show-reachable=yes")

# 覆盖率检查
set(CTEST_COVERAGE_COMMAND "gcov")

测试脚本示例​

# 在CMakeLists.txt中启用测试
enable_testing()

# 添加测试
add_test(NAME unit_tests COMMAND myapp_tests)
add_test(NAME integration_tests COMMAND myapp_integration)

# 测试属性
set_tests_properties(unit_tests PROPERTIES
    TIMEOUT 60
    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/tests
)

6. CMakePresets.json - 构建预设​

CMakePresets.json，CMake 3.19+ 引入，提供了标准化的构建配置预设，简化了不同环境下的构建过程。该文件应放在项目根目录（与 CMakeLists.txt 同级）。

{
  "version": 3,
  "configurePresets": [
    {
      "name": "debug",
      "displayName": "Debug Build",
      "binaryDir": "build/debug",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug"
      }
    },
    {
      "name": "release",
      "displayName": "Release Build",
      "binaryDir": "build/release",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "debug",
      "configurePreset": "debug"
    },
    {
      "name": "release",
      "configurePreset": "release"
    }
  ]
}

使用方式：

# 使用预设配置
cmake --preset debug
cmake --build --preset debug

# 列出可用预设
cmake --list-presets

总结​

通过这六种配置文件的合理组织和使用，可以构建出功能完整、易于维护的 CMake 项目构建系统：

• CMakeLists.txt 定义核心构建逻辑
• toolchain.cmake 处理交叉编译和工具链配置
• CMakeCache.txt 管理构建缓存和变量
• FindXXX.cmake/XXXConfig.cmake 处理依赖库查找
• CPackConfig.cmake/CTestConfig.cmake 支持打包和测试
• CMakePresets.json 提供标准化的构建预设

这种模块化的配置方式不仅提高了项目的可维护性，还增强了跨平台兼容性和团队协作效率。

1. 基础配置​

1.1 cmake_minimum_required​

指定项目所需的最低 CMake 版本。虽然不是强制要求，但建议始终显式声明，以确保构建环境兼容并避免因版本差异导致的问题。

语法：

cmake_minimum_required(VERSION x.y)

示例：

cmake_minimum_required(VERSION 3.20)

版本选择原则：

1. 基于项目使用的 CMake 特性

   • target_link_options 需要 CMake 3.13+
   • CMAKE_CXX_STANDARD 和 CMAKE_CXX_STANDARD_REQUIRED 需要 CMake 3.1+
   • qt_add_executable 需要 CMake 3.16+

2. 基于第三方库要求

   • Qt 6 官方要求 CMake 3.16+
   • OpenCV 4.5+ 推荐 CMake 3.10+

1.2 project​

定义项目名称、版本号和编程语言。

语法：

project(ProjectName VERSION major.minor.patch [LANGUAGES ...])

示例：

project(MyAwesomeApp VERSION 1.2.3 LANGUAGES CXX)

参数说明：

• ProjectName: 项目名称，用于生成工程文件名和变量 PROJECT_NAME
• VERSION: 版本号（主版本.次版本.补丁版本），自动生成以下变量：
  • PROJECT_VERSION
  • PROJECT_VERSION_MAJOR
  • PROJECT_VERSION_MINOR
  • PROJECT_VERSION_PATCH
• LANGUAGES: 支持的编程语言，可选值：
  • C: C 语言
  • CXX: C++ 语言
  • Fortran: Fortran 语言
  • ASM: 汇编语言

注意事项：

• 如果不指定 LANGUAGES，默认启用 C 和 CXX
• 建议明确指定所需语言以避免不必要的编译器检测

2. 目标管理​

2.1 add_executable​

定义并创建一个可执行文件目标，将指定的源文件编译链接成可运行的程序（如 Windows 的 .exe 文件）。

语法：

add_executable(TargetName [WIN32] [MACOSX_BUNDLE] source1 source2 ...)

参数说明：

• TargetName: 目标名称
• WIN32: Windows 平台上创建 GUI 程序（无控制台窗口）
• MACOSX_BUNDLE: macOS 平台上创建 .app 应用包
• source1 source2 ...: 源文件列表

基础示例：

add_executable(MyApp
    src/main.cpp
    src/app.cpp
)

跨平台示例：

# 收集源文件
file(GLOB_RECURSE SOURCES "src/*.cpp")

# 根据平台添加不同选项
if(WIN32)
    add_executable(MyApp WIN32 ${SOURCES})
elseif(APPLE)
    add_executable(MyApp MACOSX_BUNDLE ${SOURCES})
else()
    add_executable(MyApp ${SOURCES})
endif()

注意事项：