Dait's 技术小栈

C语言实现面向对象编程（OOP）补充内容

Fri, 24 Apr 2026 00:00:00 GMT

C语言实现面向对象编程（OOP）补充内容

上篇内容实现了继承与多态，但围绕指针转换和虚函数调用安全还有几个关键问题没有展开。本补充专题将集中讲解向上转型、向下转型（container_of）和虚函数防御，并配以可运行的测试代码，帮助你彻底理清转型机制与防御式编程的配合方式。

一、向上转型

向上转型是指将派生类指针赋值给基类指针，编译器保证安全，无需任何额外代码。

1.1 安全的前提：基类作为首成员

我们始终把基类对象放在派生类的第一个位置：

typedef struct Student {
    Person base_;        /* 必须作为第一个成员 */
    char   school_[50];
} Student;

这样，《C 语言标准》中“结构体首成员地址与结构体地址相同”的规则保证了：

Student*、&(s->base_) 和 (Person*)s 这三个指针的值完全相同。
向上转型 Person* p = (Person*)s; 是一次零开销的类型视角切换，编译器保证安全。
通过 p 访问 age_、name_ 的偏移量与访问 base_.age_、base_.name_ 完全一致。

我们可以用一段简单的代码验证这三个地址的一致性：

Student* stu = Student_newWith("Bob", 20, "XYZ University");
Person*  p   = (Person*)stu;

printf("Student*    = %p\n", (void*)stu);
printf("&base_      = %p\n", (void*)&stu->base_);
printf("(Person*)s  = %p\n", (void*)p);
// 三个输出完全相同，验证首成员规则

1.2 如果基类不在首成员会发生什么？

故意打乱布局（切勿模仿）：

typedef struct Student {
    int    id;
    Person base_;       /* 不再在开头 */
    char   school_[50];
} Student;

内存布局变为：

此时 (Person*)s 强制转换仍指向 id，编译器就会错误地将 id 的字节当作 name_ 的开始。向上转型立即失效，整个“is‑a”关系崩塌。因此必须死守铁律：基类永远作为派生类的第一个成员。

1.3 多个派生类的内存分布示例

当有多个不同的派生类（如 Student 和 Teacher）都以 Person 作为首成员时，它们的内存布局均保持“基类前缀”一致，多态统一接口就此成立。

新增一个 Teacher 类型：

typedef struct {
    Person base_;         /* 首成员 */
    char   subject_[50];
    int    years_;
} Teacher;

此时两种对象在内存中的排布如下：

无论 Student 还是 Teacher，其起始部分都是一个完整的 Person。因此 (Person*)stu 与 (Person*)tch 都直接复用对象首地址，可以安全地通过基类指针操作公共数据或调用虚函数，这正是多态能作用于不同派生类的内存根基。

我们可以用以下代码打印地址并演示多态调用：

Student* stu = Student_newWith("Bob",   20, "XYZ University");
Teacher* tch = Teacher_newWith("Alice", 35, "Physics", 10);

printf("=== Student 布局 ===\n");
printf("Student*    = %p\n", (void*)stu);
printf("&base_      = %p\n", (void*)&stu->base_);
printf("&school_    = %p\n", (void*)&stu->school_);

printf("\n=== Teacher 布局 ===\n");
printf("Teacher*    = %p\n", (void*)tch);
printf("&base_      = %p\n", (void*)&tch->base_);
printf("&subject_   = %p\n", (void*)&tch->subject_);
printf("&years_     = %p\n", (void*)&tch->years_);

Person* ps = (Person*)stu;
Person* pt = (Person*)tch;
printf("\n(Person*)Student = %p  ( == Student* )\n", (void*)ps);
printf("(Person*)Teacher = %p  ( == Teacher* )\n", (void*)pt);

/* 多态调用 */
ps->vtable_->print_(ps);   // 实际执行 Student_print_impl
pt->vtable_->print_(pt);   // 实际执行 Teacher_print_impl

运行结果（地址值因环境而异，但相等关系固定）：

=== Student 布局 ===
Student*    = 0x55a7c2d4b2a0
&base_      = 0x55a7c2d4b2a0
&school_    = 0x55a7c2d4b2d8

=== Teacher 布局 ===
Teacher*    = 0x55a7c2d4b320
&base_      = 0x55a7c2d4b320
&subject_   = 0x55a7c2d4b358
&years_     = 0x55a7c2d4b38c

(Person*)Student = 0x55a7c2d4b2a0  ( == Student* )
(Person*)Teacher = 0x55a7c2d4b320  ( == Teacher* )
[Student] 姓名：Bob，年龄：20，学校：XYZ University
[Teacher] 姓名：Alice，年龄：35，科目：Physics

从输出中可以清楚看到：每个派生类的首地址、基类成员地址、向上转型后的 Person* 地址三者完全一致。这就是多态统一接口得以成立的内存基石——只要基类放在首位，任何派生类都可以被安全地视为基类对象来操作。

二、向下转型：container_of

向下转型是从基类指针恢复出派生类指针。由于 C 语言没有运行时类型信息，向下转型的安全性由程序员负责。这里介绍 Linux 内核中经典的 container_of 宏，它利用编译期偏移量计算实现零开销转换。

2.1 关键工具：offsetof

offsetof 是 C 标准库（<stddef.h>）提供的宏，用于计算结构体中某个成员相对于结构体起始地址的字节偏移：

#include <stddef.h>

size_t offset = offsetof(Student, base_);   // 编译期计算出 base_ 在 Student 中的偏移

当 base_ 是 Student 的第一个成员时，offsetof(Student, base_) 的值为 0；如果不是首成员，则返回对应的正数偏移。它在编译期求值，运行时零开销。

2.2 地址回推原理

假设我们已经有一个指向 base_ 的有效指针 Person* p，并且我们知道这个 base_ 属于某个 Student 对象。那么要得到 Student*，只需从 p 往回减去 base_ 在 Student 中的偏移量即可：

把 p 转成字节指针 (char*)p，以便进行精确的字节级地址运算。
减去 offsetof(Student, base_)，就得到 Student 的起始地址。
最后将结果强制转换为 Student*。

整个过程用一行代码表达：

Student* s = (Student*)((char*)p - offsetof(Student, base_));

当 base_ 是首成员时，偏移量为 0，这行代码等价于 (Student*)p；当 base_ 不是首成员时，它也能正确减去相应偏移，但前提是 p 确实来自一个 Student 对象。

2.3 封装成宏（container_of）

将上面的通用逻辑提取为宏，就可以用于任意结构体和成员：

#define container_of(ptr, type, member) \
    ((type *)((char *)(ptr) - offsetof(type, member)))

该宏接收三个参数：

ptr：指向成员的指针；
type：包含该成员的结构体类型；
member：成员名称。

它返回指向外层结构体的指针。这一宏正是从 Linux 内核 中发展而来的经典设计。在内核中，大量结构体通过内嵌链表头或其他基础结构来连接，container_of 使得代码可以从一个内嵌成员的地址反向获取完整的结构体对象，极大促进了内核数据结构库的灵活性和可重用性。

2.4 在继承模拟中使用

在我们的 OOP 框架中，base_ 是派生类的首成员，向下转型可以直接用 container_of 完成：

Student* stu = Student_newWith("Bob", 20, "XYZ University");
Person*  p   = (Person*)stu;                 /* 向上转型 */

/* 向下转型：前提是 p 确实来自 Student */
Student* recovered = container_of(p, Student, base_);
printf("学校：%s\n", recovered->school_);   /* 安全访问 */

由于 offsetof(Student, base_) 为 0，container_of 实质就是一次类型强转，没有算术运算开销。

2.5 风险与使用原则

container_of 不进行任何类型检查。如果你传入的 p 实际不是从 Student 来的：

Person*  p = Person_newWith("Alice", 30);
Student* s = container_of(p, Student, base_);  /* 灾难！ */
printf("%s\n", s->school_);                     /* 未定义行为 */

程序会毫无警告地破坏内存。因此使用 container_of 向下转型必须建立在严格的上下文保证之上。如果需要运行时类型安全，应结合虚表中的类型标签（详见前文）进行判断。

三、虚函数防御

虚函数调用链 对象 → 虚表 → 函数指针 中任何一个环节为空都会导致崩溃。防御式编程必须覆盖所有环节。

3.1 核心防御手段

构造时立即绑定虚表 —— 对象“出生”即具备完整虚表。
声明 vtable_ 为 const VTable\* —— 阻挡意外篡改。
每个函数内部检查指针 —— self、vtable_、具体函数指针，逐一校验。
销毁严格使用虚表的 destroy_ —— 保证释放完整派生类内存。
调用方在销毁后置 NULL —— 杜绝悬垂指针。

3.2 安全调用宏

封装一个宏，统一处理检查，且兼容各种派生类指针甚至空指针：

#define SAFE_CALL(obj, func) \
    do { \
        Person* _self_ = (Person*)(obj); \
        if ((_self_) && (_self_)->vtable_ && (_self_)->vtable_->func) { \
            (_self_)->vtable_->func(_self_); \
        } \
    } while(0)

设计要点：

先将 obj 显式转为 Person*。得益于基类首成员规则，任何有效的派生类指针（Student*、Teacher* 等）都可以安全地转为 Person*；而 NULL 转为 Person* 仍是 NULL。
依次检查 _self_、虚表指针、具体函数指针，任一为空则跳过调用，杜绝崩溃。
虚函数内部根据实际对象的虚表，依然能正确执行派生类的重写版本，不影响多态。

使用示例：

Person* p = Person_newWith("Alice", 30);
SAFE_CALL(p, print_);          /* 正常调用 */
SAFE_CALL(NULL, print_);       /* obj 为 NULL，宏自动跳过，不崩溃 */

3.3 防御检查清单

检查点	防御动作	避免的后果
对象指针 `_self_`	`if (_self_ == NULL) return;`	空指针解引用崩溃
虚表指针 `vtable_`	`if (_self_->vtable_ == NULL) return;`	调用到随机地址
函数指针	`if (_self_->vtable_->func == NULL) return;`	执行“纯虚函数”
销毁后	调用方将指针置 `NULL`	重复释放或悬垂指针使用

四、完整测试代码与运行结果

以下测试代码综合演示了向上转型的地址验证（含多派生类）、向下转型（container_of）以及 SAFE_CALL 宏的防御效果。代码可直接编译运行。

/**
 * test_cast_and_defense.c
 * 演示向上转型（含多派生类地址对比）、向下转型（container_of）和虚函数防御宏。
 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stddef.h>        /* offsetof */

/* ----------  container_of 宏 ---------- */
#define container_of(ptr, type, member) \
    ((type *)((char *)(ptr) - offsetof(type, member)))

/* ---------- 基类 Person ---------- */
typedef struct Person {
    const struct VTable* vtable_;
    char name_[50];
    int  age_;
} Person;

typedef struct VTable {
    void (*print_)(void* self);
    void (*greet_)(void* self);
    void (*destroy_)(void* self);
} VTable;

/* ---------- 派生类 Student ---------- */
typedef struct {
    Person base_;
    char   school_[50];
} Student;

/* ---------- 派生类 Teacher ---------- */
typedef struct {
    Person base_;
    char   subject_[50];
    int    years_;
} Teacher;

/* ---------- 虚函数实现 ---------- */
void Person_print_impl(void* self) {
    Person* p = (Person*)self;
    printf("[Person] 姓名：%s，年龄：%d\n", p->name_, p->age_);
}
void Person_greet_impl(void* self) {
    Person* p = (Person*)self;
    printf("[Person] 你好，我是%s！\n", p->name_);
}
void Person_destroy_impl(void* self) {
    free(self);
}

void Student_print_impl(void* self) {
    Student* s = (Student*)self;
    printf("[Student] 姓名：%s，年龄：%d，学校：%s\n",
           s->base_.name_, s->base_.age_, s->school_);
}
void Student_greet_impl(void* self) {
    Student* s = (Student*)self;
    printf("[Student] 你好，我是%s，来自%s！\n",
           s->base_.name_, s->school_);
}
void Student_destroy_impl(void* self) {
    free(self);
}

void Teacher_print_impl(void* self) {
    Teacher* t = (Teacher*)self;
    printf("[Teacher] 姓名：%s，年龄：%d，科目：%s\n",
           t->base_.name_, t->base_.age_, t->subject_);
}
void Teacher_greet_impl(void* self) {
    Teacher* t = (Teacher*)self;
    printf("[Teacher] 同学们好，我是%s老师，教%s。\n", t->base_.name_, t->subject_);
}
void Teacher_destroy_impl(void* self) {
    free(self);
}

/* ---------- 静态虚表 ---------- */
static const VTable Person_vtable = {
    .print_   = Person_print_impl,
    .greet_   = Person_greet_impl,
    .destroy_ = Person_destroy_impl
};

static const VTable Student_vtable = {
    .print_   = Student_print_impl,
    .greet_   = Student_greet_impl,
    .destroy_ = Student_destroy_impl
};

static const VTable Teacher_vtable = {
    .print_   = Teacher_print_impl,
    .greet_   = Teacher_greet_impl,
    .destroy_ = Teacher_destroy_impl
};

/* ---------- 构造函数 ---------- */
Person* Person_newWith(const char* name, int age) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (!self) return NULL;
    self->vtable_ = &Person_vtable;
    self->age_ = age;
    strncpy(self->name_, name, sizeof(self->name_) - 1);
    self->name_[sizeof(self->name_) - 1] = '\0';
    return self;
}

Student* Student_newWith(const char* name, int age, const char* school) {
    Student* self = (Student*)malloc(sizeof(Student));
    if (!self) return NULL;
    self->base_.vtable_ = &Student_vtable;
    self->base_.age_ = age;
    strncpy(self->base_.name_, name, sizeof(self->base_.name_) - 1);
    self->base_.name_[sizeof(self->base_.name_) - 1] = '\0';
    strncpy(self->school_, school, sizeof(self->school_) - 1);
    self->school_[sizeof(self->school_) - 1] = '\0';
    return self;
}

Teacher* Teacher_newWith(const char* name, int age,
                         const char* subject, int years) {
    Teacher* self = (Teacher*)malloc(sizeof(Teacher));
    if (!self) return NULL;
    self->base_.vtable_ = &Teacher_vtable;
    self->base_.age_ = age;
    strncpy(self->base_.name_, name, sizeof(self->base_.name_) - 1);
    self->base_.name_[sizeof(self->base_.name_) - 1] = '\0';
    strncpy(self->subject_, subject, sizeof(self->subject_) - 1);
    self->subject_[sizeof(self->subject_) - 1] = '\0';
    self->years_ = years;
    return self;
}

/* ---------- 安全调用宏 ---------- */
#define SAFE_CALL(obj, func) \
    do { \
        Person* _self_ = (Person*)(obj); \
        if ((_self_) && (_self_)->vtable_ && (_self_)->vtable_->func) { \
            (_self_)->vtable_->func(_self_); \
        } \
    } while(0)

/* ---------- 测试入口 ---------- */
int main(void) {
    /* 0. 多派生类内存布局验证 */
    Student* stu = Student_newWith("Bob", 20, "XYZ University");
    Teacher* tch = Teacher_newWith("Alice", 35, "Physics", 10);

    printf("=== Student 内存布局 ===\n");
    printf("Student*    = %p\n", (void*)stu);
    printf("&base_      = %p\n", (void*)&stu->base_);
    printf("&school_    = %p\n", (void*)&stu->school_);

    printf("\n=== Teacher 内存布局 ===\n");
    printf("Teacher*    = %p\n", (void*)tch);
    printf("&base_      = %p\n", (void*)&tch->base_);
    printf("&subject_   = %p\n", (void*)&tch->subject_);
    printf("&years_     = %p\n", (void*)&tch->years_);

    Person* ps = (Person*)stu;
    Person* pt = (Person*)tch;
    printf("\n(Person*)Student = %p  ( == Student* )\n", (void*)ps);
    printf("(Person*)Teacher = %p  ( == Teacher* )\n", (void*)pt);

    /* 1. 向上转型与多态调用 */
    printf("\n=== 向上转型与多态 ===\n");
    SAFE_CALL(ps, print_);   // Student 版本
    SAFE_CALL(pt, print_);   // Teacher 版本

    /* 2. 向下转型（container_of） */
    Student* recovered = container_of(ps, Student, base_);
    printf("\n=== 向下转型（container_of） ===\n");
    printf("学校：%s\n", recovered->school_);
    printf("stu == recovered : %d\n", (void*)stu == (void*)recovered);

    /* 3. 销毁 */
    stu->base_.vtable_->destroy_(stu);
    tch->base_.vtable_->destroy_(tch);

    /* 4. 虚函数防御测试 */
    printf("\n=== 虚函数防御测试 ===\n");
    SAFE_CALL(NULL, print_);        // 传入 NULL，宏安全跳过
    ps = NULL;
    SAFE_CALL(ps, print_);          // ps 置空后也安全跳过

    return 0;
}

完整运行结果：

=== Student 内存布局 ===
Student*    = 0x55a7c2d4b2a0
&base_      = 0x55a7c2d4b2a0
&school_    = 0x55a7c2d4b2d8

=== Teacher 内存布局 ===
Teacher*    = 0x55a7c2d4b320
&base_      = 0x55a7c2d4b320
&subject_   = 0x55a7c2d4b358
&years_     = 0x55a7c2d4b38c

(Person*)Student = 0x55a7c2d4b2a0  ( == Student* )
(Person*)Teacher = 0x55a7c2d4b320  ( == Teacher* )

=== 向上转型与多态 ===
[Student] 姓名：Bob，年龄：20，学校：XYZ University
[Teacher] 姓名：Alice，年龄：35，科目：Physics

=== 向下转型（container_of） ===
学校：XYZ University
stu == recovered : 1

=== 虚函数防御测试 ===

（防御测试部分无任何输出，证明空指针被安全跳过，未引发崩溃。）

小结

向上转型由基类首成员规则保证，多个派生类内存布局的实例证明：只要基类在首位，向上转型地址完全一致，多态接口可无缝工作。
向下转型通过 container_of 宏实现，它基于 offsetof 在编译期计算偏移量，反推外层结构体指针，精巧高效（源自 Linux 内核）。但转型安全性完全由程序员保证，来源错误将导致未定义行为。
虚函数防御借助修正后的 SAFE_CALL 宏（先转为 Person* 再检查）和构造/销毁规范，系统性消除了空指针与悬垂指针调用的风险。

C语言实现面向对象编程（OOP）基础教程

Mon, 20 Apr 2026 00:00:00 GMT

C语言实现面向对象编程（OOP）基础教程

本教程面向已掌握C语言基础的读者，希望通过C语言自身机制来理解面向对象编程（OOP）的一些底层实现思路。我们依次模拟封装、成员函数、this指针、信息隐藏、继承与多态等常见特性，纯用C逐步构建，不求面面俱到，但求每一步都清晰可运行。全文共六章，每节配有完整的示例代码、分段讲解以及实践中容易踩的坑，希望能为你的OOP学习提供一个参考。

::github{repo="daitcl/oop"}

一、封装成员变量

抽象：从具体事物中提取共同特征（属性）和共同行为。
封装：将抽象出的数据（成员变量）组合成一个整体——结构体（struct）。

在C语言中，结构体支持数据封装。根据抽象的定义我们通过构建一个 Person 类型的结构体，其中包含年龄和姓名。

1.1 结构体定义与构造函数

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

/* 结构体：Person，表示人的基本信息 */
typedef struct Person {
    int age_;           /**< 年龄 */
    char name_[50];     /**< 姓名（最多 49 个有效字符 + '\0'） */
} Person;

通过 typedef struct Person {...} Person;，我们将年龄和姓名这两个属性封装成一个新的数据类型，完成了数据层面的封装。

为了让使用者更方便、更安全地创建和初始化 Person 对象，我们为其提供专门的构造函数。

/**
 * @brief 在堆上创建 Person 对象（无参构造）
 * @return 成功返回指向 Person 的指针，失败返回 NULL
 */
Person* Person_new(void) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (self == NULL) {
        return NULL;    /* 内存分配失败 */
    }

    /* 初始化为安全的默认值 */
    self->age_ = 0;
    self->name_[0] = '\0';
    return self;
}

/**
 * @brief 在堆上创建 Person 对象，并用指定参数初始化
 * @param age  年龄
 * @param name 姓名（C 字符串）
 * @return 成功返回指向 Person 的指针，失败返回 NULL
 */
Person* Person_newWith(int age, const char* name) {
    Person* self = Person_new();   /* 复用无参构造 */
    if (self == NULL) {
        return NULL;
    }

    self->age_ = age;

    /* 安全复制姓名，防止缓冲区溢出 */
    strncpy(self->name_, name, sizeof(self->name_) - 1);
    self->name_[sizeof(self->name_) - 1] = '\0';   /* 确保以 '\0' 结尾 */
    return self;
}

注意：这两个函数的返回值类型都是 Person*，也就是说它们会返回新构造出来的对象的指针，供外部使用。这也是一种模拟“构造函数返回对象”的惯用写法。

创建对象时，我们可以选择两种不同的方式——栈上直接初始化和堆上动态构造。

int main(void) {
    /* ---------- 方式 1：栈上对象 ---------- */
    Person p1 = {18, "张三"};       /* 直接初始化 */
    /* ---------- 方式 2：堆上对象 ---------- */
    Person* p2 = Person_newWith(20, "李四");
    if (p2 != NULL) {
        free(p2);          /* 必须手动释放，防止内存泄漏 */
    }

    return 0;
}

选择不同的构造方式，决定了对象创建的位置（栈/堆），进而影响了其生命周期管理方式。按需选取即可。

栈上对象 p1：随函数调用自动创建，作用域结束时自动销毁，无需手动干预，适合生命周期短、大小确定的对象。
堆上对象 p2：通过 Person_newWith（内部调用 malloc）在堆上分配，生命周期可控，必须显式 free 释放，适合需要跨函数传递或大小动态变化的对象。

接下来，我们为 Person 添加两个操作数据的函数，以此演示如何通过指针来使用封装好的成员。

/**
 * @brief 打印 Person 对象的信息
 * @param self 指向 Person 对象的指针
 */
void Person_print(Person* self) {
    if (self != NULL) {
        printf("年龄：%d，姓名：%s\n", self->age_, self->name_);
    }
}

/**
 * @brief 让 Person 对象打招呼
 * @param self 指向 Person 对象的指针
 */
void Person_greet(Person* self) {
    if (self != NULL) {
        printf("%s说：你好！\n", self->name_);
    }
}

/**
 * @brief 销毁堆上创建的 Person 对象（释放内存）
 * @param self 指向待销毁对象的指针
 */
void Person_delete(Person* self) {
    free(self);
}

在这些函数里，我们显式地传入 Person* self 指针来读取和操作 Person 中的数据。这种写法类似于 C++ 成员函数背后隐藏的 this 指针，也是 C 语言模拟面向对象行为的基础。

调用示例如下：

int main(void) {
    /* ---------- 方式 1：栈上对象 ---------- */
    Person p1 = {18, "张三"};       /* 直接初始化 */
    Person_print(&p1);              /* 传递栈对象的地址 */

    /* ---------- 方式 2：堆上对象 ---------- */
    Person* p2 = Person_newWith(20, "李四");
    if (p2 != NULL) {
        Person_print(p2);
        Person_delete(p2);          /* 必须手动释放，防止内存泄漏 */
    }

    return 0;
}

运行结果：

年龄：18，姓名：张三
年龄：20，姓名：李四
李四说：你好！

1.2 要点小结

用 typedef struct 将属性打包，实现数据封装。
函数统一接收 Person* self 指针操作对象（模拟 this）。
堆对象必须 Person_delete，栈对象自动回收。
始终用 strncpy + 手动置 '\0' 防止缓冲区溢出。

1.3 完整代码如下

/**
 * test1.c
 * 最简单的 C 语言结构体用法，数据与函数分离。
 * 演示栈对象和堆对象的创建、使用与销毁。
 */

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

/* 结构体：Person，表示人的基本信息 */
typedef struct Person {
    int age_;           /**< 年龄 */
    char name_[50];     /**< 姓名（最多 49 个有效字符 + '\0'） */
} Person;

/**
 * @brief 在堆上创建 Person 对象（无参构造）
 * @return 成功返回指向 Person 的指针，失败返回 NULL
 */
Person* Person_new(void) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (self == NULL) {
        return NULL;    /* 内存分配失败 */
    }

    /* 初始化为安全的默认值 */
    self->age_ = 0;
    self->name_[0] = '\0';
    return self;
}

/**
 * @brief 在堆上创建 Person 对象，并用指定参数初始化
 * @param age  年龄
 * @param name 姓名（C 字符串）
 * @return 成功返回指向 Person 的指针，失败返回 NULL
 */
Person* Person_newWith(int age, const char* name) {
    Person* self = Person_new();   /* 复用无参构造 */
    if (self == NULL) {
        return NULL;
    }

    self->age_ = age;

    /* 安全复制姓名，防止缓冲区溢出 */
    strncpy(self->name_, name, sizeof(self->name_) - 1);
    self->name_[sizeof(self->name_) - 1] = '\0';   /* 确保以 '\0' 结尾 */
    return self;
}

/**
 * @brief 打印 Person 对象的信息
 * @param self 指向 Person 对象的指针
 */
void Person_print(Person* self) {
    if (self != NULL) {
        printf("年龄：%d，姓名：%s\n", self->age_, self->name_);
    }
}

/**
 * @brief 让 Person 对象打招呼
 * @param self 指向 Person 对象的指针
 */
void Person_greet(Person* self) {
    if (self != NULL) {
        printf("%s说：你好！\n", self->name_);
    }
}

/**
 * @brief 销毁堆上创建的 Person 对象（释放内存）
 * @param self 指向待销毁对象的指针
 */
void Person_delete(Person* self) {
    free(self);
}

int main(void) {
    /* ---------- 方式 1：栈上对象 ---------- */
    /* 这种写法（聚合初始化）要求初始化值的类型、顺序与结构体成员完全一致，且字符串字面量不能超过数组长度。 */
    Person p1 = {18, "张三"};       /* 直接初始化 */
    Person_print(&p1);              /* 传递栈对象的地址 */

    /* ---------- 方式 2：堆上对象 ---------- */
    Person* p2 = Person_newWith(20, "李四");
    if (p2 != NULL) {
        Person_print(p2);
        Person_delete(p2);          /* 必须手动释放，防止内存泄漏 */
    }

    return 0;
}

二、封装成员函数

在C语言中，函数是全局的。为了让结构体实现“自带”行为，可以在结构体中存放函数指针，这些指针指向具体的操作函数。调用时通过 对象.函数指针(参数) 的语法，模拟C++的成员函数。

2.1 修改结构体，加入函数指针

首先，我们在 Person 结构体中增加函数指针成员：

/**
 * test2.c
 * 在结构体中添加函数指针成员，模拟 C++ 的成员函数。
 * 每个对象单独存储函数指针（内存开销较大），通过指针调用实现行为绑定。
 */

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

/* 前向声明，便于结构体内使用自身类型指针 */
typedef struct Person Person;

/**
 * 结构体：Person
 * 包含数据成员（age_, name_）和函数指针成员（print_, sayHello_, destroy_）。
 */
struct Person {
    int age_;               /**< 年龄 */
    char name_[50];         /**< 姓名 */

    /* 函数指针成员（模拟成员函数） */
    void (*print_)(Person* self);       /**< 打印信息 */
    void (*greet_)(Person* self);    /**< 打招呼 */
    void (*destroy_)(Person* self);     /**< 销毁对象（仅用于堆对象） */
};

注意：因为这些函数指针的参数类型为 Person*，所以需要先用 typedef struct Person Person; 进行前向声明。

接下来，我们需要在构造函数里完成函数指针与具体函数的绑定，这样通过 对象.函数指针(参数) 调用时才知道执行哪个函数。

/**
 * @brief 在堆上创建 Person 对象（无参构造）
 * @return 成功返回指向 Person 的指针，失败返回 NULL
 */
Person* Person_new(void) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (self == NULL) return NULL;

    /* 初始化数据成员 */
    self->age_ = 0;
    self->name_[0] = '\0';

    /* 绑定函数指针（每个对象独立存储一份） */
    self->print_    = Person_print_impl;
    self->greet_ = Person_greet_impl;
    self->destroy_  = Person_destroy_impl;

    return self;
}

/**
 * @brief 在堆上创建 Person 对象，并用指定参数初始化
 * @param age  年龄
 * @param name 姓名
 * @return 成功返回指向 Person 的指针，失败返回 NULL
 */
Person* Person_newWith(int age, const char* name) {
    Person* self = Person_new();
    if (self == NULL) return NULL;

    self->age_ = age;
    strncpy(self->name_, name, sizeof(self->name_) - 1);
    self->name_[sizeof(self->name_) - 1] = '\0';
    return self;
}

由此，我们就可以写出使用函数指针的 main 示例：

int main(void) {
    /* ---------- 栈上对象：必须手动初始化函数指针 ---------- */
    Person p1;                     /* 无法再用 {18, "张三"} 聚合初始化，因为结构体含函数指针 */
    p1.age_ = 18;
    strncpy(p1.name_, "张三", sizeof(p1.name_) - 1);
    p1.name_[sizeof(p1.name_) - 1] = '\0';

    /* 手动绑定函数指针（若未绑定直接调用会段错误） */
    p1.print_   = Person_print_impl;
    p1.greet_   = Person_greet_impl;
    p1.destroy_ = NULL;            /* 栈对象绝不可调用 destroy，设为 NULL 更安全 */

    p1.print_(&p1);                /* 通过函数指针调用，显式传入 &p1 */

    /* ---------- 堆上对象：构造函数已自动绑定 ---------- */
    Person* p2 = Person_newWith(20, "李四");
    if (p2 != NULL) {
        p2->print_(p2);
        p2->greet_(p2);            /* 可以调用多个行为函数 */
        p2->destroy_(p2);          /* 释放堆内存 */
    }

    return 0;
}

运行结果：

年龄：18，姓名：张三
年龄：20，姓名：李四
李四说：你好！

2.2 要点小结

函数指针成员：void (*print_)(Person* self); 声明了一个指向函数的指针，该函数接受 Person* 且无返回值。
绑定：在构造函数中将全局函数地址赋给指针成员，对象便“拥有”了行为。
调用：p->print_(p) 需要显式传入 p 自身，因为函数指针无法自动获取 this。
栈对象注意事项：
- 因结构体含函数指针，不便使用聚合初始化，需逐成员赋值。
- 函数指针必须手动绑定，否则调用会崩溃。
- destroy_ 应设为 NULL，严禁对栈对象执行 free。

2.3 完整代码

（此处放置完整的、修正后的 test2.c 代码，与上面展示的一致，包括函数实现的原型声明和 _impl 函数的定义。）

/**
 * test2.c
 * 在结构体中添加函数指针成员，模拟 C++ 的成员函数。
 * 每个对象单独存储函数指针（内存开销较大），通过指针调用实现行为绑定。
 */

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

/* 前向声明，便于结构体内使用自身类型指针 */
typedef struct Person Person;

/**
 * 结构体：Person
 * 包含数据成员（age_, name_）和函数指针成员（print_, greet_, destroy_）。
 */
struct Person {
    int age_;               /**< 年龄 */
    char name_[50];         /**< 姓名 */

    /* 函数指针成员（模拟成员函数） */
    void (*print_)(Person* self);       /**< 打印信息 */
    void (*greet_)(Person* self);    /**< 打招呼 */
    void (*destroy_)(Person* self);     /**< 销毁对象（仅用于堆对象） */
};

/* 函数实现的原型声明 */
void Person_print_impl(Person* self);
void Person_greet_impl(Person* self);
void Person_destroy_impl(Person* self);

/**
 * @brief 在堆上创建 Person 对象（无参构造）
 * @return 成功返回指向 Person 的指针，失败返回 NULL
 */
Person* Person_new(void) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (self == NULL) return NULL;

    /* 初始化数据成员 */
    self->age_ = 0;
    self->name_[0] = '\0';

    /* 绑定函数指针（每个对象独立存储一份） */
    self->print_    = Person_print_impl;
    self->greet_ = Person_greet_impl;
    self->destroy_  = Person_destroy_impl;

    return self;
}

/**
 * @brief 在堆上创建 Person 对象，并用指定参数初始化
 * @param age  年龄
 * @param name 姓名
 * @return 成功返回指向 Person 的指针，失败返回 NULL
 */
Person* Person_newWith(int age, const char* name) {
    Person* self = Person_new();
    if (self == NULL) return NULL;

    self->age_ = age;
    strncpy(self->name_, name, sizeof(self->name_) - 1);
    self->name_[sizeof(self->name_) - 1] = '\0';
    return self;
}

/**
 * @brief 打印 Person 对象信息（函数指针绑定的实现）
 * @param self 指向当前对象的指针
 */
void Person_print_impl(Person* self) {
    if (self != NULL) {
        printf("年龄：%d，姓名：%s\n", self->age_, self->name_);
    }
}

/**
 * @brief 打招呼的实现
 */
void Person_greet_impl(Person* self) {
    if (self != NULL) {
        printf("%s说：你好！\n", self->name_);
    }
}

/**
 * @brief 销毁堆对象的实现
 */
void Person_destroy_impl(Person* self) {
    free(self);
}

int main(void) {
    /* ---------- 栈上对象：必须手动初始化函数指针 ---------- */
    Person p1;
    p1.age_ = 18;
    strncpy(p1.name_, "张三", sizeof(p1.name_) - 1);
	p1.name_[sizeof(p1.name_) - 1] = '\0';

    /* 绑定函数指针（若未绑定直接调用会导致段错误） */
    p1.print_    = Person_print_impl;
    p1.greet_ = Person_greet_impl;
    p1.destroy_  = Person_destroy_impl;   /* 栈对象通常不应调用 destroy_ */

    p1.print_(&p1);   /* 通过函数指针调用，需显式传入对象自身 */

    /* ---------- 堆上对象：构造函数已自动绑定 ---------- */
    Person* p2 = Person_newWith(20, "李四");
    if (p2 != NULL) {
        p2->print_(p2);
        p2->destroy_(p2);   /* 释放堆内存 */
    }

    return 0;
}

三、隐藏this指针（仅供学习）

C++ 的成员函数可以隐式获取 this 指针，调用时无需显式传递对象自身。在 C 语言中，我们可以用一个全局变量来模拟这种机制：在调用成员函数前，先把当前对象的地址存入一个全局指针，函数内部直接访问该全局指针即可。

⚠️ 警告：这种方法非线程安全，且极易因忘记设置全局指针而出错。本节仅用于帮助理解 this 的工作原理，实际项目中切勿使用。工程上的安全做法会在第五章介绍。

3.1 引入全局 this 指针

先把 Person 中的函数指针改为无参形式，因为它们将依靠全局指针来获取操作对象。

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

typedef struct Person Person;

struct Person {
    int age_;
    char name_[50];

    /* 函数指针成员，均为无参函数（内部通过全局 person_this 访问对象） */
    void (*print_)(void);
    void (*greet_)(void);
    void (*destroy_)(void);
};

/* 全局 this 指针，指向当前正在操作的对象 */
Person* person_this = NULL;

/* 函数实现的原型声明 */
void Person_print_impl(void);
void Person_greet_impl(void);
void Person_destroy_impl(void);

上述代码将 print_、greet_ 和 destroy_ 的参数列表置为 void，意味着调用时不再需要手动传入对象指针。对象本身通过全局变量 person_this 来定位，这就是对 this 指针的模拟。

此外，我们定义一个宏 PERSON_CAST，用来在调用前方便地设置 person_this，同时返回对象指针，以便支持链式调用风格。

/**
 * 宏：PERSON_CAST
 * 将全局 person_this 设为指定对象，并返回该对象指针。
 * 用法：PERSON_CAST(p2)->print_();
 */
#define PERSON_CAST(object) (person_this = (object))

构造函数同样需要适配：在创建对象并绑定函数指针时，自动将 person_this 指向新对象。

/**
 * @brief 堆上创建 Person 对象（无参构造）
 */
Person* Person_new(void) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (self == NULL) return NULL;

    self->age_ = 0;
    self->name_[0] = '\0';

    /* 绑定无参函数指针 */
    self->print_   = Person_print_impl;
    self->greet_   = Person_greet_impl;
    self->destroy_ = Person_destroy_impl;

    person_this = self;   /* 使新对象成为当前操作对象 */
    return self;
}

/**
 * @brief 堆上创建 Person 对象（带参构造）
 */
Person* Person_newWith(int age, const char* name) {
    Person* self = Person_new();
    if (self == NULL) return NULL;

    self->age_ = age;
    strncpy(self->name_, name, sizeof(self->name_) - 1);
    self->name_[sizeof(self->name_) - 1] = '\0';
    return self;
}

函数实现内部直接使用 person_this 来访问成员，不再需要 self 参数：

void Person_print_impl(void) {
    if (person_this != NULL) {
        printf("年龄：%d，姓名：%s\n", person_this->age_, person_this->name_);
    }
}

void Person_greet_impl(void) {
    if (person_this != NULL) {
        printf("%s说：你好！\n", person_this->name_);
    }
}

void Person_destroy_impl(void) {
    free(person_this);
    /* 注意：这里未将 person_this 置为 NULL，外部需自行管理 */
}

调用示例如下：

int main(void) {
    /* ---------- 栈上对象 ---------- */
    Person p1;
    p1.age_ = 18;
    strncpy(p1.name_, "张三", sizeof(p1.name_) - 1);
    p1.name_[sizeof(p1.name_) - 1] = '\0';

    /* 手动绑定函数指针 */
    p1.print_   = Person_print_impl;
    p1.greet_   = Person_greet_impl;
    p1.destroy_ = NULL;                    /* 栈对象绝不调用 destroy_ */

    person_this = &p1;                     /* 设置当前操作对象 */
    p1.print_();                           /* 无需传参，直接调用 */

    /* ---------- 堆上对象 ---------- */
    Person* p2 = Person_newWith(20, "李四");
    if (p2 != NULL) {
        PERSON_CAST(p2)->print_();         /* 通过宏设置 this 并调用 */
        PERSON_CAST(p2)->greet_();         /* 另一个行为 */
        PERSON_CAST(p2)->destroy_();       /* 释放堆内存 */
    }

    return 0;
}

运行结果：

年龄：18，姓名：张三
年龄：20，姓名：李四
李四说：你好！

3.2 要点小结

全局 person_this：扮演了 this 指针的角色，函数内部通过它找到当前对象。
无参函数指针：void (*print_)(void) 等不再需要显式传入 Person*，调用更接近 C++ 的语法。
PERSON_CAST 宏：一行代码完成“设置当前对象 + 返回对象指针”，模拟 obj->method() 的连贯写法。
栈对象：仍需手动绑定函数指针，且使用前必须将 person_this 指向该对象。切勿调用 destroy_。
严重局限：任何时刻只有一个 person_this，嵌套调用或多线程下会完全混乱，详见下一节。

3.3 缺陷一览

缺陷	描述
非线程安全	多个线程同时修改全局 `person_this`，会导致数据错乱或崩溃
不支持重入	在一个成员函数内部调用另一个对象的成员函数时，`person_this` 会被覆盖
极易忘记设置	栈对象若忘记写 `person_this = &p1;`，调用行为函数会操作空指针或错误对象
销毁后悬空	`destroy_` 释放内存后 `person_this` 未置 `NULL`，后续误用造成悬垂指针

请牢记：本方案仅用于教学演示，帮助理解 C++ 中 this 的幕后机制。实际开发中请直接跳至第5章的工程化实现。

3.4 完整代码

/**
 * test3.c
 * 引入全局指针 person_this 模拟 C++ 的 this 指针，使成员函数无需显式传参。
 * 仅供理解原理，非线程安全，切勿在工程中使用。
 */

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

typedef struct Person Person;

struct Person {
    int age_;
    char name_[50];

    /* 函数指针成员，均为无参函数（依赖全局 person_this） */
    void (*print_)(void);
    void (*greet_)(void);
    void (*destroy_)(void);
};

/* 全局 this 指针，指向当前操作的对象 */
Person* person_this = NULL;

/**
 * 宏：将全局 person_this 设置为指定对象，并返回该对象指针，支持链式调用。
 */
#define PERSON_CAST(object) (person_this = (object))

/* 函数原型 */
void Person_print_impl(void);
void Person_greet_impl(void);
void Person_destroy_impl(void);

Person* Person_new(void) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (self == NULL) return NULL;

    self->age_ = 0;
    self->name_[0] = '\0';

    self->print_   = Person_print_impl;
    self->greet_   = Person_greet_impl;
    self->destroy_ = Person_destroy_impl;

    person_this = self;
    return self;
}

Person* Person_newWith(int age, const char* name) {
    Person* self = Person_new();
    if (self == NULL) return NULL;

    self->age_ = age;
    strncpy(self->name_, name, sizeof(self->name_) - 1);
    self->name_[sizeof(self->name_) - 1] = '\0';
    return self;
}

void Person_print_impl(void) {
    if (person_this != NULL) {
        printf("年龄：%d，姓名：%s\n", person_this->age_, person_this->name_);
    }
}

void Person_greet_impl(void) {
    if (person_this != NULL) {
        printf("%s说：你好！\n", person_this->name_);
    }
}

void Person_destroy_impl(void) {
    free(person_this);
}

int main(void) {
    /* 栈上对象 */
    Person p1;
    p1.age_ = 18;
    strncpy(p1.name_, "张三", sizeof(p1.name_) - 1);
    p1.name_[sizeof(p1.name_) - 1] = '\0';

    p1.print_   = Person_print_impl;
    p1.greet_   = Person_greet_impl;
    p1.destroy_ = NULL;                     /* 栈对象严禁释放 */

    person_this = &p1;
    p1.print_();

    /* 堆上对象 */
    Person* p2 = Person_newWith(20, "李四");
    if (p2 != NULL) {
        PERSON_CAST(p2)->print_();
        PERSON_CAST(p2)->greet_();
        PERSON_CAST(p2)->destroy_();       /* 释放堆内存 */
    }

    return 0;
}

四、隐藏成员变量

C语言的结构体所有成员默认都是公有的。若想实现私有成员（外部代码无法直接访问），可使用不透明指针技术：在公开接口中只暴露一个 void* 指针，真正的数据定义在源文件内部，外部完全看不到细节。

4.1 使用私有数据结构

将真正的年龄、姓名放入一个独立的 PersonPrivate 结构体，对外只暴露 void* private_ 指针。同时，函数指针依然使用全局 person_this，不传 self。

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

/* 前向声明 */
typedef struct Person Person;

/* 私有数据结构体（定义在 .c 文件内部，此处为演示写在同一文件） */
typedef struct PersonPrivate {
    int age_;
    char name_[50];
} PersonPrivate;

/* 公有接口结构体 */
struct Person {
    void* private_;                     /* 指向私有数据的指针（不透明） */

    /* 无参函数指针，依赖全局 person_this */
    void (*print_)(void);
    void (*greet_)(void);
    void (*destroy_)(void);
    void (*setAge_)(int age);
    int  (*getAge_)(void);
    const char* (*getName_)(void);
    void (*setName_)(const char* name);
};

/* 全局 this 指针（线程不安全，仅演示用） */
Person* person_this = NULL;

/* 设置当前对象并支持链式调用的宏 */
#define PERSON_CAST(object) (person_this = (object))

/* 函数原型 */
void Person_print_impl(void);
void Person_greet_impl(void);
void Person_destroy_impl(void);
void Person_setAge_impl(int age);
int  Person_getAge_impl(void);
const char* Person_getName_impl(void);
void Person_setName_impl(const char* name);

Person* Person_new(void);
Person* Person_newWith(int age, const char* name);

/* ---- 私有数据的分配与释放 ---- */
static PersonPrivate* PersonPrivate_new(void) {
    PersonPrivate* priv = (PersonPrivate*)malloc(sizeof(PersonPrivate));
    if (priv != NULL) {
        priv->age_ = 0;
        priv->name_[0] = '\0';
    }
    return priv;
}

static void PersonPrivate_delete(PersonPrivate* priv) {
    free(priv);
}

/* ---- 构造函数 ---- */
Person* Person_new(void) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (self == NULL) return NULL;

    self->private_ = PersonPrivate_new();
    if (self->private_ == NULL) {
        free(self);
        return NULL;
    }

    self->print_   = Person_print_impl;
    self->greet_   = Person_greet_impl;
    self->destroy_ = Person_destroy_impl;
    self->setAge_  = Person_setAge_impl;
    self->getAge_  = Person_getAge_impl;
    self->getName_ = Person_getName_impl;
    self->setName_ = Person_setName_impl;

    person_this = self;   /* 自动设为当前对象 */
    return self;
}

Person* Person_newWith(int age, const char* name) {
    Person* self = Person_new();
    if (self == NULL) return NULL;

    PersonPrivate* priv = (PersonPrivate*)self->private_;
    priv->age_ = age;
    strncpy(priv->name_, name, sizeof(priv->name_) - 1);
    priv->name_[sizeof(priv->name_) - 1] = '\0';
    return self;
}

/* ---- 行为函数实现（通过全局 person_this 访问对象和私有数据） ---- */
void Person_print_impl(void) {
    if (person_this == NULL) return;
    PersonPrivate* priv = (PersonPrivate*)person_this->private_;
    if (priv != NULL) {
        printf("年龄：%d，姓名：%s\n", priv->age_, priv->name_);
    }
}

void Person_greet_impl(void) {
    if (person_this == NULL) return;
    PersonPrivate* priv = (PersonPrivate*)person_this->private_;
    if (priv != NULL) {
        printf("%s说：你好！\n", priv->name_);
    }
}

void Person_destroy_impl(void) {
    if (person_this == NULL) return;
    /* 先释放私有数据，再释放外壳 */
    if (person_this->private_ != NULL) {
        PersonPrivate_delete((PersonPrivate*)person_this->private_);
        person_this->private_ = NULL;
    }
    free(person_this);
    /* 注意：未将 person_this 置 NULL，外部调用后容易误用 */
}

void Person_setAge_impl(int age) {
    if (person_this == NULL) return;
    PersonPrivate* priv = (PersonPrivate*)person_this->private_;
    if (priv != NULL) priv->age_ = age;
}

int Person_getAge_impl(void) {
    if (person_this == NULL) return -1;
    PersonPrivate* priv = (PersonPrivate*)person_this->private_;
    return priv ? priv->age_ : -1;
}

const char* Person_getName_impl(void) {
    if (person_this == NULL) return NULL;
    PersonPrivate* priv = (PersonPrivate*)person_this->private_;
    return priv ? priv->name_ : NULL;
}

void Person_setName_impl(const char* name) {
    if (person_this == NULL || name == NULL) return;
    PersonPrivate* priv = (PersonPrivate*)person_this->private_;
    if (priv != NULL) {
        strncpy(priv->name_, name, sizeof(priv->name_) - 1);
        priv->name_[sizeof(priv->name_) - 1] = '\0';
    }
}

/* ---- 使用示例 ---- */
int main(void) {
    /* ---------- 栈上对象：手动设置私有数据和函数指针 ---------- */
    Person p1;
    p1.private_ = PersonPrivate_new();
    if (p1.private_ == NULL) return 1;

    p1.print_   = Person_print_impl;
    p1.greet_   = Person_greet_impl;
    p1.destroy_ = NULL;                     /* 栈对象绝不能调用 destroy_ */
    p1.setAge_  = Person_setAge_impl;
    p1.getAge_  = Person_getAge_impl;
    p1.getName_ = Person_getName_impl;
    p1.setName_ = Person_setName_impl;

    person_this = &p1;
    p1.setName_("张三");
    p1.setAge_(18);
    p1.print_();

    /* 释放私有数据（栈对象自身内存不释放） */
    PersonPrivate_delete((PersonPrivate*)p1.private_);
    p1.private_ = NULL;

    /* ---------- 堆上对象：构造函数自动绑定 ---------- */
    Person* p2 = Person_newWith(20, "李四");
    if (p2 != NULL) {
        PERSON_CAST(p2)->print_();
        PERSON_CAST(p2)->destroy_();   /* destroy_ 会释放私有数据和外壳 */
    }

    return 0;
}

运行结果：

年龄：18，姓名：张三
年龄：20，姓名：李四

4.2 要点小结

不透明指针 void\* private_：对外隐藏了 PersonPrivate 的成员细节，外部代码无法直接访问年龄或姓名。
私有数据分配：通过 PersonPrivate_new() 在堆上分配，Person 只是保存其地址。栈对象需手动调用分配与释放。
全局 person_this 依然存在：所有无参函数仍依赖它来定位当前对象，带来了第三章的全部局限性。
接口完整：除打印和打招呼外，增加了 setAge_、getAge_、getName_、setName_ 等访问器，模拟了完整的成员函数集。

4.3 注意事项

缺陷	描述
全局 this 不安全	非线程安全，且嵌套调用时 `person_this` 会被覆盖，与第三章相同
栈对象初始化繁琐	需要手动分配 `private_`、逐个绑定函数指针，极易遗漏
destroy 后悬空	`Person_destroy_impl` 未将 `person_this` 置 `NULL`，可能导致悬垂指针
栈对象不宜 destroy	栈对象外壳在栈上，`free` 会导致崩溃，必须将 `destroy_` 设为 `NULL`

本节展示了信息隐藏的基本手段。实际项目中，建议直接阅读第五章，它去掉了全局 this，提供了栈/堆统一的安全初始化方式。

4.4 完整代码

（上述代码合并即为完整可运行程序，不再单独赘列。注意编译时需包含 stdio.h、stdlib.h、string.h。）

五、多文件与显式 this 参数（推荐）

综合前几章的探索，最安全、可维护、可工程化的方式是：显式传递 self 指针（彻底避免全局变量），结合多文件组织，并支持栈对象和堆对象的统一初始化。

数据成员通过不透明指针 PersonPrivate* 隐藏，保护内部细节。
所有函数显式接收 Person* self，完全可重入，线程安全。
栈对象使用 Person_init / Person_cleanup，堆对象使用 Person_newWith / destroy。

5.1 头文件 person.h

/**
 * person.h
 * Person 类的公有接口声明。
 * 采用私有数据封装，支持栈对象初始化与清理。
 */

#ifndef PERSON_H
#define PERSON_H

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

/* 前向声明私有数据结构 */
typedef struct PersonPrivate PersonPrivate;

/**
 * 公有接口结构体 Person
 * 外部只看到一个不透明指针和一组函数指针。
 */
typedef struct Person {
    PersonPrivate* private_;            /* 私有数据（不透明） */

    /* 行为函数指针，每个都显式接收 Person* self */
    void (*print)(struct Person* self);
    void (*greet)(struct Person* self);
    void (*destroy)(struct Person* self);
    void (*setAge)(struct Person* self, int age);
    int  (*getAge)(struct Person* self);
    const char* (*getName)(struct Person* self);
    void (*setName)(struct Person* self, const char* name);
} Person;

/* 堆对象构造函数 */
Person* Person_new(void);
Person* Person_newWith(int age, const char* name);

/* 栈对象初始化与清理 */
void Person_init(Person* self);
void Person_cleanup(Person* self);

#endif /* PERSON_H */

5.2 实现文件 person.c

/**
 * person.c
 * Person 类的实现。
 * 私有数据结构体定义在此，对外不可见。
 * 所有成员函数实现均以 static 限定，仅通过公有接口暴露。
 */

#include "person.h"

/* ==================== 私有数据结构体完整定义 ==================== */
struct PersonPrivate {
    int age_;
    char name_[50];
};

/* ==================== 静态成员函数（内部可见） ==================== */
static void Person_print_impl(Person* self) {
    if (self == NULL || self->private_ == NULL) return;
    PersonPrivate* priv = self->private_;
    printf("年龄：%d，姓名：%s\n", priv->age_, priv->name_);
}

static void Person_greet_impl(Person* self) {
    if (self == NULL || self->private_ == NULL) return;
    PersonPrivate* priv = self->private_;
    printf("%s说：你好！\n", priv->name_);
}

static void Person_destroy_impl(Person* self) {
    if (self == NULL) return;
    /* 释放私有数据 */
    if (self->private_ != NULL) {
        free(self->private_);
        self->private_ = NULL;
    }
    free(self);   /* 注意：堆对象会被释放，栈对象不应调用此函数 */
}

static void Person_setAge_impl(Person* self, int age) {
    if (self == NULL || self->private_ == NULL) return;
    self->private_->age_ = age;
}

static int Person_getAge_impl(Person* self) {
    if (self == NULL || self->private_ == NULL) return -1;
    return self->private_->age_;
}

static const char* Person_getName_impl(Person* self) {
    if (self == NULL || self->private_ == NULL) return NULL;
    return self->private_->name_;
}

static void Person_setName_impl(Person* self, const char* name) {
    if (self == NULL || self->private_ == NULL || name == NULL) return;
    strncpy(self->private_->name_, name, sizeof(self->private_->name_) - 1);
    self->private_->name_[sizeof(self->private_->name_) - 1] = '\0';
}

/* ==================== 私有数据分配与释放 ==================== */
static PersonPrivate* PersonPrivate_new(void) {
    PersonPrivate* priv = (PersonPrivate*)malloc(sizeof(PersonPrivate));
    if (priv != NULL) {
        priv->age_ = 0;
        priv->name_[0] = '\0';
    }
    return priv;
}

/* ==================== 构造函数（堆对象） ==================== */
Person* Person_new(void) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (self == NULL) return NULL;

    self->private_ = PersonPrivate_new();
    if (self->private_ == NULL) {
        free(self);
        return NULL;
    }

    self->print   = Person_print_impl;
    self->greet   = Person_greet_impl;
    self->destroy = Person_destroy_impl;
    self->setAge  = Person_setAge_impl;
    self->getAge  = Person_getAge_impl;
    self->getName = Person_getName_impl;
    self->setName = Person_setName_impl;

    return self;
}

Person* Person_newWith(int age, const char* name) {
    Person* self = Person_new();
    if (self == NULL) return NULL;

    self->private_->age_ = age;
    strncpy(self->private_->name_, name, sizeof(self->private_->name_) - 1);
    self->private_->name_[sizeof(self->private_->name_) - 1] = '\0';
    return self;
}

/* ==================== 栈对象初始化与清理 ==================== */
void Person_init(Person* self) {
    if (self == NULL) return;

    self->private_ = PersonPrivate_new();
    if (self->private_ == NULL) {
        fprintf(stderr, "栈对象私有内存分配失败\n");
        return;
    }

    self->print   = Person_print_impl;
    self->greet   = Person_greet_impl;
    self->destroy = NULL;               /* 栈对象绝对不能 free 外壳 */
    self->setAge  = Person_setAge_impl;
    self->getAge  = Person_getAge_impl;
    self->getName = Person_getName_impl;
    self->setName = Person_setName_impl;
}

void Person_cleanup(Person* self) {
    if (self == NULL) return;
    if (self->private_ != NULL) {
        free(self->private_);
        self->private_ = NULL;
    }
    /* 不释放 self，它在栈上 */
}

5.3 测试文件 test5.c

/**
 * test5.c
 * 演示栈对象与堆对象的统一使用方式。
 */

#include "person.h"

int main(void) {
    /* ---------- 栈上对象 ---------- */
    Person p1;
    Person_init(&p1);

    p1.setName(&p1, "张三");
    p1.setAge(&p1, 18);
    p1.print(&p1);               /* 年龄：18，姓名：张三 */
    p1.greet(&p1);               /* 张三说：你好！ */

    Person_cleanup(&p1);

    /* ---------- 堆上对象 ---------- */
    Person* p2 = Person_newWith(20, "李四");
    if (p2 != NULL) {
        p2->print(p2);           /* 年龄：20，姓名：李四 */
        p2->destroy(p2);         /* 释放私有数据 + 外壳 */
    }

    return 0;
}

运行结果：

年龄：18，姓名：张三
张三说：你好！
年龄：20，姓名：李四

5.4 要点小结

显式 self 指针：所有函数都接收 Person* self 作为第一个参数，无需全局状态，天然线程安全。
不透明私有数据：PersonPrivate 定义在 .c 文件中，外部代码只能通过 setAge、getName 等接口访问，无法直接触碰成员。
栈/堆统一接口：
- 栈对象：声明 Person p1; → Person_init(&p1) → 使用 → Person_cleanup(&p1)。
- 堆对象：Person* p = Person_newWith(...) → 使用 → p->destroy(p)。
防御性编程：每个函数开头均检查 self 和 private_ 是否为 NULL，避免崩溃。
栈对象 destroy 设为 NULL：在 Person_init 中明确将其置空，防止误调导致对栈内存执行 free。

5.5 注意事项

问题	说明
栈对象必须配对	必须有 `Person_init` 和 `Person_cleanup`，否则内存泄漏或重复释放
栈对象禁止调用 destroy	`destroy` 内部会 `free(self)`，栈对象调用即崩溃
堆对象销毁后指针悬空	`p2->destroy(p2)` 后 `p2` 成为悬垂指针，应避免再次使用
多文件编译	对外只提供 `person.h`，私有结构体修改不影响用户代码

5.6 完整项目文件

person.h —— 公有接口（如上）
person.c —— 实现（如上）
test5.c —— 测试（如上）

编译命令（gcc）：

  gcc -std=c99 -Wall -Wextra -o test5 test5.c person.c

六、继承与多态

继承：让新类型（派生类）复用已有类型（基类）的属性和行为。多态：通过基类接口调用函数时，实际执行的是派生类的版本，即“同一接口，不同表现”。

C 语言没有原生的继承和多态语法，但可以通过结构体嵌套（将基类作为派生类的第一个成员）和函数指针（或虚函数表）来模拟。

6.1 简单继承——每个对象独立函数指针

最直观的方式是基类中声明函数指针成员，派生类通过包含基类实例“继承”这些指针。构造函数中，派生类可以重写某些函数指针，也可以复用基类的实现。

/**
 * test6_inheritance_simple.c
 * 每个对象独立存储函数指针，直观但内存开销较大。
 */

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

/* ---------------------------- 基类 Person ---------------------------- */
typedef struct Person {
    char name_[50];
    int age_;

    /* 函数指针成员，显式传递 self（使用 void* 以兼容派生类） */
    void (*print_)(void* self);
    void (*greet_)(void* self);
} Person;

/* 基类构造函数 */
Person* Person_new(void) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (self == NULL) return NULL;
    self->age_ = 0;
    self->name_[0] = '\0';
    /* 函数指针在构造函数中不绑定，由派生类或专用初始化函数处理 */
    self->print_ = NULL;
    self->greet_ = NULL;
    return self;
}

/* 基类行为实现 */
void Person_print_impl(void* self) {
    Person* p = (Person*)self;
    printf("[Person] 姓名：%s，年龄：%d\n", p->name_, p->age_);
}

void Person_greet_impl(void* self) {
    Person* p = (Person*)self;
    printf("[Person] 你好，我是%s！\n", p->name_);
}

/* 便捷的初始化函数：为基类对象绑定默认行为 */
void Person_init_default(Person* self) {
    if (self == NULL) return;
    self->print_ = Person_print_impl;
    self->greet_ = Person_greet_impl;
}

/* ---------------------------- 派生类 Student ---------------------------- */
/* 结构体嵌套：基类对象作为第一个成员，保证内存兼容 */
typedef struct Student {
    Person base_;           /* 继承的属性和函数指针 */
    char school_[50];
} Student;

/* 派生类构造函数：分配内存并初始化 */
Student* Student_new(void) {
    Student* self = (Student*)malloc(sizeof(Student));
    if (self == NULL) return NULL;
    self->base_.age_ = 0;
    self->base_.name_[0] = '\0';
    self->school_[0] = '\0';

    /* 重写 print_，继承 greet_（绑定基类实现） */
    self->base_.print_ = Student_print_impl;
    self->base_.greet_ = Person_greet_impl;   /* 行为继承 */

    return self;
}

void Student_print_impl(void* self) {
    Student* s = (Student*)self;
    printf("[Student] 姓名：%s，年龄：%d，学校：%s\n",
           s->base_.name_, s->base_.age_, s->school_);
}

关键设计：Student 的第一个成员是 Person base_。这样，指向 Student 的指针可以安全地转换为 Person*，且访问 base_ 的成员与直接访问 Person 内存完全一致。

使用示例：

int main(void) {
    /* 创建基类对象并手动绑定函数指针 */
    Person* person = Person_new();
    Person_init_default(person);                /* 绑定默认行为 */
    strncpy(person->name_, "Alice", sizeof(person->name_) - 1);
    person->name_[sizeof(person->name_) - 1] = '\0';
    person->age_ = 30;
    person->print_(person);
    person->greet_(person);
    free(person);

    /* 创建派生类对象（构造函数已绑定函数指针） */
    Student* student = Student_new();
    strncpy(student->base_.name_, "Bob", sizeof(student->base_.name_) - 1);
    student->base_.name_[sizeof(student->base_.name_) - 1] = '\0';
    student->base_.age_ = 20;
    strncpy(student->school_, "XYZ University", sizeof(student->school_) - 1);
    student->school_[sizeof(student->school_) - 1] = '\0';

    student->base_.print_(student);             /* 调用 Student 自己的 print_ */
    student->base_.greet_(student);             /* 调用继承自 Person 的 greet_ */
    free(student);

    return 0;
}

运行结果：

[Person] 姓名：Alice，年龄：30
[Person] 你好，我是Alice！
[Student] 姓名：Bob，年龄：20，学校：XYZ University
[Person] 你好，我是Bob！

6.1.1 要点小结

结构体嵌套：派生类把基类作为第一个成员，实现“is‑a”关系。
函数指针重写：派生类在构造函数中将某些函数指针指向自己的实现，其余保留基类实现，即可完成行为继承。
内存布局：因为基类在派生类的最前面，(Person*)student 是安全的向上转型。
每个对象独立指针：虽然简单直观，但每个对象都保存一份函数指针（此处 2 个指针 16 字节），对象数量多时内存开销较大。

6.1.2 注意事项

陷阱	后果	避免方法
忘记绑定函数指针	调用时跳转到 `NULL`，程序崩溃	构造函数中统一绑定，或提供类似 `Person_init_default` 的初始化函数
错误使用 `strcpy`	名称过长可能溢出 `name_[50]`	统一使用 `strncpy` + 末尾置 `'\0'`
向上转型时误解内存	若基类不是第一个成员，强制转换后布局错乱	始终将基类放在结构体最前面

6.2 虚函数表（vtable）——多态的高效实现

独立函数指针会为每个对象重复存储相同的函数地址。更好的方式是将这些指针集中放在一个静态常量表里，每个对象只保存一个指向该表的指针。这正是 C++ 虚函数的底层机制。

/**
 * test7_vtable.c
 * 使用虚函数表（vtable）实现继承与多态。
 */

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

/* 前向声明 */
typedef struct Person Person;
typedef struct Student Student;

/* 虚函数表结构体，使用 const 保护 */
typedef struct VTable {
    void (*print_)(void* self);
    void (*greet_)(void* self);
    void (*destroy_)(void* self);
} VTable;

/* 基类 Person */
struct Person {
    const VTable* vtable_;      /* 指向虚表的指针（不可修改） */
    char name_[50];
    int age_;
};

/* 派生类 Student */
struct Student {
    Person base_;               /* 继承 */
    char school_[50];
};

/* --------------- 函数实现声明 --------------- */
void Person_print_impl(void* self);
void Person_greet_impl(void* self);
void Person_destroy_impl(void* self);

void Student_print_impl(void* self);
void Student_greet_impl(void* self);
void Student_destroy_impl(void* self);

/* 静态虚表（每个类一个），使用指定初始化器，强健且易读 */
static const VTable Person_vtable = {
    .print_   = Person_print_impl,
    .greet_   = Person_greet_impl,
    .destroy_ = Person_destroy_impl
};

static const VTable Student_vtable = {
    .print_   = Student_print_impl,
    .greet_   = Student_greet_impl,
    .destroy_ = Student_destroy_impl
};

/* --------------- 基类构造函数 --------------- */
Person* Person_new(void) {
    Person* self = (Person*)malloc(sizeof(Person));
    if (self == NULL) return NULL;
    self->vtable_ = &Person_vtable;   /* 绑定虚表 */
    self->age_ = 0;
    self->name_[0] = '\0';
    return self;
}

Person* Person_newWith(const char* name, int age) {
    Person* self = Person_new();
    if (self == NULL) return NULL;
    self->age_ = age;
    strncpy(self->name_, name, sizeof(self->name_) - 1);
    self->name_[sizeof(self->name_) - 1] = '\0';
    return self;
}

/* --------------- 派生类构造函数 --------------- */
Student* Student_new(void) {
    Student* self = (Student*)malloc(sizeof(Student));
    if (self == NULL) return NULL;
    self->base_.vtable_ = &Student_vtable;   /* 绑定派生类虚表 */
    self->base_.age_ = 0;
    self->base_.name_[0] = '\0';
    self->school_[0] = '\0';
    return self;
}

Student* Student_newWith(const char* name, int age, const char* school) {
    Student* self = Student_new();
    if (self == NULL) return NULL;
    self->base_.age_ = age;
    strncpy(self->base_.name_, name, sizeof(self->base_.name_) - 1);
    self->base_.name_[sizeof(self->base_.name_) - 1] = '\0';
    strncpy(self->school_, school, sizeof(self->school_) - 1);
    self->school_[sizeof(self->school_) - 1] = '\0';
    return self;
}

/* --------------- 函数实现 --------------- */
void Person_print_impl(void* self) {
    Person* p = (Person*)self;
    printf("[Person] 姓名：%s，年龄：%d\n", p->name_, p->age_);
}

void Person_greet_impl(void* self) {
    Person* p = (Person*)self;
    printf("[Person] 你好，我是%s！\n", p->name_);
}

void Person_destroy_impl(void* self) {
    free(self);
}

void Student_print_impl(void* self) {
    Student* s = (Student*)self;
    printf("[Student] 姓名：%s，年龄：%d，学校：%s\n",
           s->base_.name_, s->base_.age_, s->school_);
}

void Student_greet_impl(void* self) {
    Student* s = (Student*)self;
    printf("[Student] 你好，我是%s，来自%s！\n",
           s->base_.name_, s->school_);
}

void Student_destroy_impl(void* self) {
    free(self);
}

使用示例（多态调用）：

int main(void) {
    Person* p = Person_newWith("Alice", 30);
    Student* s = Student_newWith("Bob", 20, "XYZ University");

    /* 通过基类指针调用，实现多态 */
    Person* ps = (Person*)s;          /* 向上转型 */

    p->vtable_->print_(p);            /* Person 版本 */
    ps->vtable_->print_(ps);          /* 多态：实际调用 Student 的 print_ */
    ps->vtable_->greet_(ps);          /* 多态：实际调用 Student 的 greet_ */

    /* 销毁（虚表中有统一的 destroy_） */
    p->vtable_->destroy_(p);
    ps->vtable_->destroy_(ps);        /* 正确释放 Student 内存 */

    return 0;
}

运行结果：

[Person] 姓名：Alice，年龄：30
[Student] 姓名：Bob，年龄：20，学校：XYZ University
[Student] 你好，我是Bob，来自XYZ University！

6.2.1 要点小结

虚表 VTable：将函数指针集中存储在一个静态 const 结构体中，每个类一个实例。
对象存储 vtable_ 指针：所有对象共享同一个虚表，内存节省（每个对象仅增加一个指针）。
多态调用：通过 obj->vtable_->print_(obj) 这种“二次跳转”实现晚绑定。
构造时绑定：在 Person_new / Student_new 中将 vtable_ 指向对应虚表，确保对象创建完毕即可使用。
const 保护：虚表声明为 static const，防止运行时被意外篡改。

6.2.2 注意事项

陷阱	后果	避免方法
虚表未正确初始化	`vtable_` 为 `NULL` 或野指针	构造函数中必须立即绑定虚表
向上转型后误用 `free`	若派生类大小与基类不同，导致内存错误	通过虚表内的 `destroy_` 释放，保证使用正确的 `free`
忘记给派生类定义独立的虚表	调用的仍是基类函数，丢失多态	每个派生类都定义自己的 `static const VTable`
字符串处理不安全	任意一处 `strcpy` 都可能溢出	全项目统一使用 `strncpy` + 末尾置 `'\0'`

6.3 多文件

在真实项目中，我们通常将每个类的声明放在独立的头文件，实现放在对应的源文件，并利用 const 保护虚表。编译时只需链接目标文件，修改私有实现不会影响用户代码。

文件结构示例：

project/
├── person.h
├── person.c
├── student.h
├── student.c
└── main.c

person.h（公有接口，遵循最小包含原则）

#ifndef PERSON_H
#define PERSON_H

#ifdef __cplusplus
extern "C" {
#endif

/* 前向声明，隐藏实现细节 */
typedef struct Person Person;
typedef struct VTable VTable;

struct VTable {
    void (*print_)(void* self);
    void (*greet_)(void* self);
    void (*destroy_)(void* self);
};

struct Person {
    const VTable* vtable_;
    char name_[50];
    int age_;
};

/* 构造函数与公有函数 */
Person* Person_new(void);
Person* Person_newWith(const char* name, int age);
void Person_destroy(Person* self);   /* 便捷封装，直接调用虚表销毁 */

#ifdef __cplusplus
}
#endif

#endif /* PERSON_H */

student.h

#ifndef STUDENT_H
#define STUDENT_H

#include "person.h"

typedef struct Student {
    Person base_;
    char school_[50];
} Student;

Student* Student_new(void);
Student* Student_newWith(const char* name, int age, const char* school);
/* 析构函数可以直接使用 Person_destroy((Person*)student) */

#endif /* STUDENT_H */

person.c 和 student.c 的实现与 6.2 节类似，注意将虚表及实现的函数标记为 static，只通过公有接口暴露。

main.c 示例：

#include "person.h"
#include "student.h"

int main(void) {
    Person* p = Person_newWith("Alice", 30);
    Student* s = Student_newWith("Bob", 20, "XYZ University");

    p->vtable_->print_(p);                  /* Person 版本 */
    ((Person*)s)->vtable_->print_(s);       /* 多态：Student 版本 */

    Person_destroy(p);
    Person_destroy((Person*)s);             /* 正确释放 Student 内存 */

    return 0;
}

编译命令（严格模式）：

gcc -std=c99 -Wall -Wextra -pedantic -o program main.c person.c student.c

6.4 本章总结

本章展示了 C 语言模拟继承与多态的两种方式，完成了从基础封装到面向对象编程的完整演进：

简单继承（独立函数指针） 每个对象持有自己的函数指针，直观易懂。派生类通过替换部分指针实现重写，保留其余指针复用基类行为。代价是每个对象多占用函数指针的存储空间。
高效多态（虚函数表） 将函数指针集中存放在静态 const 虚表中，对象只保留一个指向虚表的指针。所有同类对象共享同一虚表，大幅节省内存。调用时通过 obj->vtable_->print_(obj) 实现运行时多态。

关键实践（贯穿全系列）：

基类放在派生类第一个成员——保证内存布局兼容，向上转型安全。
构造函数中立即绑定虚表或函数指针——对象创建完毕即可用，杜绝野指针。
虚表用 static const 保护——防止意外修改，语义更清晰。
始终使用 strncpy + 强制尾 '\0'——杜绝字符串溢出。
防御式编程——每个行为函数先检查指针有效性。

Qt6基础教程：多线程串口通信实战

Thu, 02 Apr 2026 00:00:00 GMT

Qt6基础教程：多线程串口通信实战

在实际 Qt 项目中，串口通信往往需要长时间运行、频繁收发数据。如果在 GUI 线程中直接操作 QSerialPort，则 readyRead 信号和 write 调用可能阻塞界面，造成卡顿。本文介绍一种线程安全、高内聚低耦合的设计模式：将串口操作封装到工作线程中，通过 SerialManager 对外提供简洁接口，实现串口通信与界面逻辑的完全分离。

::github{repo="daitcl/Qt-demo"}

一、创建串口工作类 `SerialWorker`

我们要设计的第一个类是 SerialWorker，它继承自 QObject，以便后续可以轻松移动到工作线程。

1.1 基本框架

头文件 serialworker.h 最开始只需要包含必要的头文件和类声明：

#ifndef SERIALWORKER_H
#define SERIALWORKER_H

#include <QObject>
#include <QSerialPort>

class SerialWorker : public QObject
{
    Q_OBJECT

};
#endif

接着添加构造函数和析构函数。注意构造时接收父对象指针，以便启用 Qt 的对象树内存管理。

class SerialWorker : public QObject
{
    Q_OBJECT
public:
    explicit SerialWorker(QObject *parent = nullptr);
    ~SerialWorker();
};

对应的实现文件 serialworker. 暂时如下：

#include "serialworker.h"
#include <QDebug>

SerialWorker::SerialWorker(QObject *parent)
    : QObject(parent)
{
}

SerialWorker::~SerialWorker()
{
}

1.2 加入串口对象成员

在 SerialWorker 中增加一个 QSerialPort 指针，并在构造函数中创建它，同时将其设置为 this 的子对象。这样，当 SerialWorker 销毁时，m_serial 会被 Qt 自动清理，无需手动 delete。

class SerialWorker : public QObject
{
    // ... 已有代码 ...
private:
    QSerialPort *m_serial = nullptr;
};

SerialWorker::SerialWorker(QObject *parent)
    : QObject(parent)
    , m_serial(new QSerialPort(this))
{
}

说明：new QSerialPort(this) 将 m_serial 作为 SerialWorker 的子对象，自动纳入 Qt 对象树。父对象析构时会递归删除所有子对象，因此我们不需要在析构函数中写 delete m_serial。

1.3 串口的打开与关闭

为了能让外部控制串口，我们提供 open 和 close 两个槽函数。由于它们将来可能被跨线程调用，所以定义为 public slots。同时，为了便于传递串口参数，先定义一个配置结构体 SerialConfig。

struct SerialConfig {
    QString portName;
    qint32 baudRate = 115200;
    QSerialPort::DataBits dataBits = QSerialPort::Data8;
    QSerialPort::Parity parity = QSerialPort::NoParity;
    QSerialPort::StopBits stopBits = QSerialPort::OneStop;
    QSerialPort::FlowControl flowControl = QSerialPort::NoFlowControl;
};

class SerialWorker : public QObject
{
    Q_OBJECT
public:
    explicit SerialWorker(QObject *parent = nullptr);
    ~SerialWorker();
public slots:
    void open(const SerialConfig &config);
    void close();
private:
    QSerialPort *m_serial = nullptr;
    void applyConfig(const SerialConfig &config);
    bool m_isOpen = false;
};

对应的实现如下：

void SerialWorker::open(const SerialConfig &config)
{
    if (m_isOpen) {
        close();  // 如果已打开，先关闭
    }
    applyConfig(config);
    m_serial->open(QIODevice::ReadWrite);
    m_isOpen = true;
}

void SerialWorker::close()
{
    if (m_serial->isOpen()) {
        m_serial->clear();
        m_serial->close();
    }
    m_isOpen = false;
}

void SerialWorker::applyConfig(const SerialConfig &config)
{
    m_serial->setPortName(config.portName);
    m_serial->setBaudRate(config.baudRate);
    m_serial->setDataBits(config.dataBits);
    m_serial->setParity(config.parity);
    m_serial->setStopBits(config.stopBits);
    m_serial->setFlowControl(config.flowControl);
}

为什么打开前要调用 close？ 如果串口已经打开，直接修改端口名、波特率等参数可能不会立即生效，有些参数（如端口名）甚至要求串口处于关闭状态。先关闭再应用新配置，可以保证所有参数按照预期重新初始化。

1.4 接收数据：解决粘包与界面卡顿

串口数据是流式传输的，readyRead 信号可能在数据未完整时就被触发。如果每收到几个字节就立即通知上层，会导致频繁的信号发射和界面刷新，效率很低。更好的做法是：将数据暂存到缓冲区，等待一小段时间（例如 100 毫秒），如果这段时间内没有新数据到来，再将完整的缓冲区数据一次性发出。这既能避免粘包，又能减少界面刷新次数。

我们使用一个 QTimer 来实现延迟聚合。同时为了防止缓冲区无限增长，设定一个最大容量（如 10 MB），超出则强制发送。

修改类定义，添加必要的成员和槽函数：

class SerialWorker : public QObject
{
    Q_OBJECT
public:
    // ... 已有 public 成员 ...
signals:
    void dataReceived(const QByteArray &data);
private slots:
    void onReadyRead();
    void onTimeout();
private:
    QSerialPort *m_serial = nullptr;
    QTimer *m_delayTimer = nullptr;
    QByteArray m_buffer;
    int m_receiveDelay = 100;   // 默认100ms
    bool m_isOpen = false;
    void applyConfig(const SerialConfig &config);
    void flushBuffer();
};

构造函数中创建定时器并连接信号：

SerialWorker::SerialWorker(QObject *parent)
    : QObject(parent)
    , m_serial(new QSerialPort(this))
    , m_delayTimer(new QTimer(this))
{
    m_delayTimer->setSingleShot(true); // 单次触发模式
    connect(m_serial, &QSerialPort::readyRead, this, &SerialWorker::onReadyRead);
    connect(m_delayTimer, &QTimer::timeout, this, &SerialWorker::onTimeout);
}

onReadyRead 以及相关辅助函数的实现：

void SerialWorker::onReadyRead()
{
    QByteArray chunk = m_serial->readAll();
    m_buffer.append(chunk);

    // 防止缓冲区无限增长（例如 10MB 上限）
    constexpr int MAX_BUFFER_SIZE = 10 * 1024 * 1024; // 10 MiB
    if (m_buffer.size() > MAX_BUFFER_SIZE) {
        flushBuffer();
    }

    if (m_receiveDelay == 0) {
        flushBuffer(); // 立即发送
    } else {
        m_delayTimer->start(m_receiveDelay); // 重启定时器
    }
}

void SerialWorker::onTimeout()
{
    flushBuffer();
}

void SerialWorker::flushBuffer()
{
    if (m_buffer.isEmpty()) return;
    emit dataReceived(m_buffer);
    m_buffer.clear();
}

核心思想：每次 readyRead 都会重置定时器，只有在延时期间没有新数据到达时，定时器才会超时并真正发出数据。这既能保证实时性，又能有效聚合小数据包。

1.5 发送数据：支持文本与十六进制

为了灵活发送数据，我们再实现一个 sendData 槽函数同时提供一个 setReceiveDelay 接口，用于动态调整接收聚合延时。

类定义中增加：

public slots:
    void sendData(const QByteArray &data);
    void setReceiveDelay(int ms);

实现如下：

void SerialWorker::sendData(const QByteArray &data)
{
    if (!m_isOpen) return;
    if (data.isEmpty()) return;

    QByteArray outData = data;
    m_serial->write(outData);
}

void SerialWorker::setReceiveDelay(int ms)
{
    m_receiveDelay = ms;
}

说明：上述 sendData 中仅完成了格式转换，实际写入操作 m_serial->write(outData) 请根据项目需要添加。同时，示例代码中 onTimeout 槽函数已在前面实现，但类声明中未显式声明，实际使用时请确保声明与定义一致。

1.6 完善错误处理与状态信号

为了便于上层感知串口状态变化和错误，我们增加一组信号：

signals:
    void opened();                          // 打开成功
    void closed();                          // 关闭成功
    void errorOccurred(const QString &errorString);
    void dataReceived(const QByteArray &data);
    void configApplied(const QString &configStr);

同时完善 open 和 sendData 的实现，增加错误检查和信号发射。

完善后的 open 函数：

void SerialWorker::open(const SerialConfig &config)
{
    if (m_isOpen) {
        close();
    }
    
    applyConfig(config);
    if (!m_serial->open(QIODevice::ReadWrite)) {
        emit errorOccurred(tr("打开串口失败: %1").arg(m_serial->errorString()));
        return;
    }
    m_isOpen = true;
    emit opened();
    emit configApplied(config.toString());  // 需要 SerialConfig 实现 toString()，或自行构造字符串
}

完善后的 sendData 函数：

void SerialWorker::sendData(const QByteArray &data)
{
    if (!m_isOpen) {
        emit errorOccurred(tr("串口未打开，无法发送数据"));
        return;
    }
    if (data.isEmpty()) return;
    
    QByteArray outData = data;
    
    qint64 written = m_serial->write(outData);
    if (written != outData.size()) {
        emit errorOccurred(tr("数据发送不完整"));
    }
}

设置接收延迟的槽函数：

void SerialWorker::setReceiveDelay(int ms)
{
    m_receiveDelay = ms;
}

至此，SerialWorker 类已经具备了打开、关闭、发送、接收（带延迟聚合）以及完整错误通知的能力。

二、创建管理类 `SerialManager`

SerialWorker 已经实现了串口的所有底层操作，但它仍然运行在创建它的线程中。为了实现真正的多线程隔离，需要一个管理类，负责：

将 SerialWorker 移动到一个独立的 QThread 中。
对外提供线程安全的调用接口（通过信号槽自动处理线程切换）。
将 SerialWorker 发出的信号转发给上层，避免上层直接与工作对象耦合。

2.1 定义 `SerialManager` 类的基本框架

创建头文件 serialmanager.h，定义 SerialManager 类，继承自 QObject。需要包含一个 QThread 成员和一个 SerialWorker 指针。

// serialmanager.h
#ifndef SERIALMANAGER_H
#define SERIALMANAGER_H

#include <QObject>
#include <QThread>
#include "serialworker.h"

class SerialManager : public QObject
{
    Q_OBJECT
public:
    explicit SerialManager(QObject *parent = nullptr);
    ~SerialManager();

private:
    QThread m_workerThread;
    SerialWorker *m_worker = nullptr;
};

#endif

2.2 添加对外公开接口

为了让 GUI 层能够控制串口，需要提供 open、close、sendData、setReceiveDelay 等函数。这些函数将被设计为 Q_INVOKABLE（方便 QML 调用，但不是必须），并且可以在任意线程中安全调用——它们内部只发射信号，不执行实际操作。

class SerialManager : public QObject
{
    Q_OBJECT
public:
    explicit SerialManager(QObject *parent = nullptr);
    ~SerialManager();

    // 对外公开接口（可从任意线程安全调用）
    Q_INVOKABLE void open(const SerialConfig &config);
    Q_INVOKABLE void close();
    Q_INVOKABLE void sendData(const QByteArray &data);
    Q_INVOKABLE void setReceiveDelay(int ms);

    // ... 其余成员
};

2.3 添加内部请求信号

公开接口本身不直接操作 SerialWorker，而是发射一个“请求信号”。这些信号会被连接到 SerialWorker 的对应槽函数。由于信号槽可以跨线程，SerialWorker 将在自己的线程中执行这些槽。

class SerialManager : public QObject
{
    // ...
signals:
    // 请求信号（用于转发给 SerialWorker）
    void requestOpen(const SerialConfig &config);
    void requestClose();
    void requestSendData(const QByteArray &data);
    void requestSetReceiveDelay(int ms);

    // 转发信号（稍后添加）
};

2.4 添加转发信号

SerialWorker 会发出一些状态信号（如 opened、dataReceived 等）。上层只需要连接 SerialManager 的信号即可，因此需要定义一组相同的信号用于转发。

class SerialManager : public QObject
{
    // ...
signals:
    // ... 请求信号

    // 转发信号（来自 SerialWorker 的事件）
    void opened();
    void closed();
    void errorOccurred(const QString &errorString);
    void dataReceived(const QByteArray &data);
    void configApplied(const QString &configStr);
};

2.5 实现构造函数

构造函数需要完成以下工作：

创建 SerialWorker 对象（此时它还在主线程）。
将工作对象移动到 m_workerThread。
连接请求信号到工作对象的槽。
连接工作对象的信号到转发信号。
启动工作线程。

// serialmanager.
#include "serialmanager.h"

SerialManager::SerialManager(QObject *parent)
    : QObject(parent)
{
    m_worker = new SerialWorker();
    m_worker->moveToThread(&m_workerThread);

    // 连接请求信号到工作对象的槽
    connect(this, &SerialManager::requestOpen, m_worker, &SerialWorker::open);
    connect(this, &SerialManager::requestClose, m_worker, &SerialWorker::close);
    connect(this, &SerialManager::requestSendData, m_worker, &SerialWorker::sendData);
    connect(this, &SerialManager::requestSetReceiveDelay, m_worker, &SerialWorker::setReceiveDelay);

    // 连接工作对象的信号到转发信号
    connect(m_worker, &SerialWorker::opened, this, &SerialManager::opened);
    connect(m_worker, &SerialWorker::closed, this, &SerialManager::closed);
    connect(m_worker, &SerialWorker::errorOccurred, this, &SerialManager::errorOccurred);
    connect(m_worker, &SerialWorker::dataReceived, this, &SerialManager::dataReceived);
    connect(m_worker, &SerialWorker::configApplied, this, &SerialManager::configApplied);

    m_workerThread.start();
}

2.6 实现析构函数

析构时需要安全地停止线程并释放工作对象。

SerialManager::~SerialManager()
{
    m_workerThread.quit();
    m_workerThread.wait();
    delete m_worker;
}

说明：m_worker 是在构造函数中用 new 创建的，并且被移到了工作线程。虽然它没有父对象，但我们在析构函数中手动 delete 是安全的，因为 wait() 保证了线程已经退出，不会再有槽函数被调用。

2.7 实现公开接口

每个公开接口只需要发射对应的请求信号。由于信号槽是异步的，调用者不会阻塞。

void SerialManager::open(const SerialConfig &config)
{
    emit requestOpen(config);
}

void SerialManager::close()
{
    emit requestClose();
}

void SerialManager::sendData(const QByteArray &data)
{
    emit requestSendData(data);
}

void SerialManager::setReceiveDelay(int ms)
{
    emit requestSetReceiveDelay(ms);
}

三、创建简易Demo

3.1 搭建基础界面与 `SerialManager` 集成

首先创建一个继承自 QWidget 的界面类，并加入必要的成员变量。

头文件 widget.h 初始结构：

#ifndef WIDGET_H
#define WIDGET_H

#include <QWidget>
#include "serial/serialmanager.h"

QT_BEGIN_NAMESPACE
namespace Ui { class Widget; }
QT_END_NAMESPACE

class Widget : public QWidget
{
    Q_OBJECT
public:
    explicit Widget(QWidget *parent = nullptr);
    ~Widget();

private:
    Ui::Widget *ui;
    SerialManager *manager = nullptr;   // 串口管理器（多线程安全）
};

#endif

实现文件 widget.cpp 构造函数：

#include "widget.h"
#include "ui_widget.h"

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , manager(new SerialManager(this))   // manager 作为子对象，自动释放
    , ui(new Ui::Widget)
{
    ui->setupUi(this);
}

Widget::~Widget()
{
    delete ui;
}

说明：SerialManager 内部已经封装了工作线程，我们只需像普通 QObject 一样创建它，并设置父对象即可。所有串口操作都可以通过 manager 的公开接口安全调用。

3.2 初始化串口参数下拉框

串口调试助手需要让用户选择波特率、数据位等参数。我们在 Widget 中添加一个私有方法 initUIConfig()，在构造函数中调用它。

在 widget.h 中添加：

private:
    void initUIConfig();

实现 initUIConfig()：

void Widget::initUIConfig()
{
    // 波特率
    ui->comBaudRate->addItems({"1200", "2400", "4800", "9600", "19200", "38400", "57600", "115200"});
    ui->comBaudRate->setEditable(true);
    ui->comBaudRate->setValidator(new QIntValidator(0, 1000000, this));
    ui->comBaudRate->setCurrentIndex(3);   // 默认 9600

    // 数据位
    ui->comDataBits->addItems({"5", "6", "7", "8"});
    ui->comDataBits->setCurrentIndex(3);   // 默认 8

    // 校验位
    ui->comParity->addItems({"Even", "Mark", "None", "Odd", "Space"});
    ui->comParity->setCurrentIndex(2);     // 默认 None

    // 停止位
    ui->comStopBits->addItems({"1", "1.5", "2"});
    ui->comStopBits->setCurrentIndex(0);   // 默认 1
}

关键点：

使用 addItems 一次性添加常用选项。

波特率设置为可编辑 + 整数校验器，方便用户手动输入非常用波特率。

默认选择最常用的参数（9600/8/N/1）。

3.3 获取可用串口列表

动态扫描系统串口是调试助手的基本功能。我们添加 getportInfo() 方法，并在构造函数中调用。

声明与实现：

// widget.h
private:
    void getportInfo();

// widget.
void Widget::getportInfo()
{
    ui->comPortName->clear();
    QList<QSerialPortInfo> ports = QSerialPortInfo::availablePorts();
    if (ports.isEmpty()) {
        ui->comPortName->addItem("无可用串口");
        ui->OpenComBtn->setEnabled(false);
        return;
    }
    ui->OpenComBtn->setEnabled(true);
    for (const QSerialPortInfo &info : ports)
        ui->comPortName->addItem(info.portName());
}

说明：

使用 QSerialPortInfo::availablePorts() 获取当前系统中的串口列表。

若无可用串口，禁用“打开串口”按钮并显示提示项。

若有串口，启用按钮并填充端口名。

3.4 打开与关闭串口

这是与 SerialManager 交互的第一步。我们需要连接按钮的点击信号，并在槽函数中调用 manager->open(config) 或 manager->close()。同时，为了知道串口何时真正打开/关闭，需要连接 SerialManager 的状态信号。

在 Widget 中添加槽函数和状态处理：

// widget.h
private slots:
    void onOpenCloseButtonClicked();
    void handleOpened();
    void handleClosed();
    void handleErrorOccurred(const QString &error);
private:
    bool isSerialOpen = false;

构造函数中连接信号：

// 在 Widget 构造函数中添加
connect(ui->OpenComBtn, &QPushButton::clicked, this, &Widget::onOpenCloseButtonClicked);
connect(manager, &SerialManager::opened, this, &Widget::handleOpened);
connect(manager, &SerialManager::closed, this, &Widget::handleClosed);
connect(manager, &SerialManager::errorOccurred, this, &Widget::handleErrorOccurred);

实现打开/关闭逻辑：

void Widget::onOpenCloseButtonClicked()
{
    if (!isSerialOpen) {
        // 准备配置
        SerialConfig config;
        config.portName = ui->comPortName->currentText();
        config.baudRate = ui->comBaudRate->currentText().toInt();

        // 数据位映射
        switch (ui->comDataBits->currentIndex()) {
        case 0: config.dataBits = QSerialPort::Data5; break;
        case 1: config.dataBits = QSerialPort::Data6; break;
        case 2: config.dataBits = QSerialPort::Data7; break;
        default: config.dataBits = QSerialPort::Data8; break;
        }
        // 校验位映射
        switch (ui->comParity->currentIndex()) {
        case 0: config.parity = QSerialPort::EvenParity; break;
        case 1: config.parity = QSerialPort::MarkParity; break;
        case 2: config.parity = QSerialPort::NoParity; break;
        case 3: config.parity = QSerialPort::OddParity; break;
        default: config.parity = QSerialPort::SpaceParity; break;
        }
        // 停止位映射
        switch (ui->comStopBits->currentIndex()) {
        case 0: config.stopBits = QSerialPort::OneStop; break;
        case 1: config.stopBits = QSerialPort::OneAndHalfStop; break;
        default: config.stopBits = QSerialPort::TwoStop; break;
        }

        manager->open(config);
        ui->OpenComBtn->setEnabled(false);
        ui->OpenComBtn->setText("正在打开...");
    } else {
        manager->close();
    }
}

void Widget::handleOpened()
{
    isSerialOpen = true;
    ui->OpenComBtn->setEnabled(true);
    ui->OpenComBtn->setText("关闭串口");
}

void Widget::handleClosed()
{
    isSerialOpen = false;
    ui->OpenComBtn->setEnabled(true);
    ui->OpenComBtn->setText("打开串口");
}

void Widget::handleErrorOccurred(const QString &error)
{
    QMessageBox::critical(this, "串口错误", error);
    isSerialOpen = false;
    ui->OpenComBtn->setEnabled(true);
    ui->OpenComBtn->setText("打开串口");
}

设计要点：

打开时先禁用按钮并显示“正在打开...”，防止重复点击。

打开成功/失败后，通过 handleOpened 或 handleErrorOccurred 恢复按钮状态。

关闭操作同样异步，最终由 handleClosed 更新界面。

3.5 实现数据发送（支持纯文本与十六进制）

SerialManager 只接受 QByteArray 类型的原始字节数据。因此，我们需要根据界面上的“Hex发送”复选框，将用户输入的文本转换成对应的字节数组。

添加槽函数和辅助方法：

// widget.h
private slots:
    void onSendButtonClicked();
private:
    void initCheckbox();          // 初始化 Hex 模式相关信号槽
    void formatTxEditForHex();    // 实时格式化 Hex 输入
    void convertTextToHex();      // 文本 -> Hex 字符串
    void convertHexToText();      // Hex 字符串 -> 文本

发送按钮槽函数实现：

void Widget::onSendButtonClicked()
{
    QString text = ui->TxEdit->toPlainText().trimmed();
    if (text.isEmpty()) return;

    bool hexFlag = ui->HexTxBox->isChecked();
    QByteArray data;

    if (hexFlag) {
        // 移除空格，校验偶数个字符
        QString hexStr = text;
        hexStr.remove(' ');
        if (hexStr.length() % 2 != 0) {
            QMessageBox::warning(this, "错误", "十六进制数据必须为偶数个字符，请补零后重试");
            return;
        }
        data = QByteArray::fromHex(hexStr.toUtf8());
        if (data.isEmpty() && !hexStr.isEmpty()) {
            QMessageBox::warning(this, "错误", "无效的十六进制数据");
            return;
        }
    } else {
        data = text.toUtf8();   // 文本模式使用 UTF-8 编码
    }
    manager->sendData(data);
}

Hex 输入辅助功能（实时格式化和模式切换）：

void Widget::initCheckbox()
{
    // 切换 Hex 发送模式时，转换当前文本框内容
    connect(ui->HexTxBox, &QCheckBox::stateChanged, this, [=](int state) {
        if (state == Qt::Checked)
            convertTextToHex();
        else
            convertHexToText();
    });

    // Hex 模式下，每次文本改变时自动添加空格、过滤非法字符
    connect(ui->TxEdit, &QTextEdit::textChanged, this, [=]() {
        if (ui->HexTxBox->isChecked())
            formatTxEditForHex();
    });
}

void Widget::formatTxEditForHex()
{
    // 实现细节参考最终源码：提取十六进制字符、每两个加空格、保持光标位置
    // 此处省略完整代码
}

void Widget::convertTextToHex()
{
    QString plainText = ui->TxEdit->toPlainText();
    QByteArray bytes = plainText.toLocal8Bit();
    QString hexStr = bytes.toHex(' ').toUpper();
    ui->TxEdit->blockSignals(true);
    ui->TxEdit->setPlainText(hexStr);
    ui->TxEdit->blockSignals(false);
}

void Widget::convertHexToText()
{
    QString hexText = ui->TxEdit->toPlainText();
    QString pureHex = hexText;
    pureHex.remove(' ');
    QByteArray bytes = QByteArray::fromHex(pureHex.toUtf8());
    if (bytes.isEmpty() && !pureHex.isEmpty()) {
        QMessageBox::warning(this, "错误", "无效的十六进制数据，无法转换为文本");
        return;
    }
    QString plainText = QString::fromLocal8Bit(bytes);
    if (plainText.isEmpty() && !bytes.isEmpty())
        plainText = QString::fromLatin1(bytes);
    ui->TxEdit->blockSignals(true);
    ui->TxEdit->setPlainText(plainText);
    ui->TxEdit->blockSignals(false);
}

关键说明：

界面层负责数据格式转换，SerialManager 保持简洁（只发送原始字节）。

Hex 模式下，提供实时格式化（自动插入空格、限制输入字符）和模式切换时的内容转换，提升用户体验。

3.6 实现数据接收与显示

接收数据通过连接 SerialManager::dataReceived 信号完成。我们可以在槽函数中根据用户设置（Hex显示、时间戳、自动换行）格式化数据并追加到接收文本框。

添加槽函数：

// widget.h
private slots:
    void handleDataReceived(const QByteArray &data);

构造函数中连接信号：

connect(manager, &SerialManager::dataReceived, this, &Widget::handleDataReceived);

实现接收处理：

void Widget::handleDataReceived(const QByteArray &data)
{
    if (data.isEmpty()) return;

    // 根据 Hex 复选框决定显示格式
    QString display;
    if (ui->HexRxBox->isChecked()) {
        display = data.toHex(' ').toUpper();
        if (!display.isEmpty()) display += ' ';
    } else {
        display = QString::fromUtf8(data);
        if (display.isEmpty()) display = QString::fromLatin1(data);
    }

    ui->RxEdit->moveCursor(QTextCursor::End);

    // 时间戳
    if (ui->TimeBox->isChecked()) {
        QString timestamp = QDateTime::currentDateTime().toString("[yyyy/MM/dd hh:mm:ss] ");
        ui->RxEdit->insertPlainText(timestamp);
    }

    ui->RxEdit->insertPlainText(display);

    // 自动换行
    if (ui->AWBox->isChecked())
        ui->RxEdit->insertPlainText("\n");

    ui->RxEdit->moveCursor(QTextCursor::End);
}

说明：

使用 data.toHex(' ') 将字节数组转换为带空格的十六进制字符串，便于阅读。

文本模式优先尝试 UTF-8 解码，失败则回退到 Latin1。

支持可选的时间戳和自动换行，所有选项实时生效。

3.7 实现定时发送

定时发送功能利用 QTimer 周期性调用发送按钮的槽函数。用户可通过复选框启用/禁用，并通过数值调节框改变间隔。

添加成员和槽函数：

// widget.h
private:
    QTimer *m_sendTimer = nullptr;
private slots:
    void onTRBoxToggled(bool checked);
    void onTimeoutSend();

构造函数中初始化定时器并连接信号：

// 在 Widget 构造函数中添加
m_sendTimer = new QTimer(this);
m_sendTimer->setSingleShot(false);
connect(m_sendTimer, &QTimer::timeout, this, &Widget::onTimeoutSend);
connect(ui->TRBox, &QCheckBox::toggled, this, &Widget::onTRBoxToggled);
connect(ui->TVBox, QOverload<int>::of(&QSpinBox::valueChanged), this, [=](int value) {
    if (m_sendTimer->isActive())
        m_sendTimer->setInterval(value);
});

实现槽函数：

void Widget::onTRBoxToggled(bool checked)
{
    if (checked) {
        int interval = ui->TVBox->value();
        if (interval <= 0) {
            QMessageBox::warning(this, "警告", "定时发送间隔必须大于0");
            ui->TRBox->setChecked(false);
            return;
        }
        m_sendTimer->setInterval(interval);
        m_sendTimer->start();
    } else {
        m_sendTimer->stop();
    }
}

void Widget::onTimeoutSend()
{
    onSendButtonClicked();   // 复用发送逻辑
}

设计说明：

定时器周期根据 ui->TVBox 的值动态调整。

启用定时发送前检查间隔合法性。

复用 onSendButtonClicked 避免重复代码。

3.8 附加功能：清空发送/接收编辑框

为了界面友好，添加两个清空按钮非常简单，使用 Lambda 表达式直接连接。

在构造函数中添加：

connect(ui->ClearRxBtn, &QPushButton::clicked, this, [=]() { ui->RxEdit->clear(); });
connect(ui->ClearTxBtn, &QPushButton::clicked, this, [=]() { ui->TxEdit->clear(); });

四、回顾与总结

通过本教程的三部分，我们完成了一个多线程串口通信模块：

SerialWorker：封装串口底层操作，利用延迟聚合优化接收效率，并提供打开、关闭、发送、错误处理等完整功能。
SerialManager：将工作对象移至独立线程，通过信号槽提供线程安全的公开接口，并将工作对象的状态信号转发给上层，实现了界面与串口逻辑的完全解耦。
**Widget **：展示了如何使用 SerialManager 构建一个串口调试助手，包括参数配置、串口扫描、数据收发（支持文本/十六进制、时间戳、自动换行）、定时发送等功能。

完整工程地址

Qt6基础教程：串口通信与Qt Serial Port模块详解

Sun, 29 Mar 2026 00:00:00 GMT

Qt6基础教程：串口通信与Qt Serial Port模块详解

Qt Serial Port 模块用于串口通信编程，主要提供了包括配置、I/O操作、RS-232引脚控制信号的获取和设置。如果要在一个项目中使用Qt Serial Port模块，需要在项目的配置文件中加入如下语句：

头文件中添加：

#include <QSerialPortInfo> //串口信息
#include <QSerialPort> //串口

使用cmake时：

find_package(Qt6 REQUIRED COMPONENTS SerialPort)
target_link_libraries(mytarget PRIVATE Qt6::SerialPort)

使用qmake时：

QT += serialport

Qt 串口的通信协议比较简单，Qt Serial Port模块中只有两个类：QSerialPortInfo和QSerialPort。

💡注意：Qt Serial Port 不支持如回声、控制CR/LF等功能

一、QSerialPortInfo

1.QSerialPortInfo 类介绍

QSerialPortInfo 是一个辅助类，用于获取系统中已连接的串口设备信息。它不直接用于通信，而是用来查询串口的名称、描述、制造商等属性，帮助用户选择合适的串口。

通过阅读官方文档可以看到QSerialPortInfo类有两个静态方法，用于获取系统串口信息：

静态方法	说明
`QList<QSerialPortInfo> availablePorts()`	返回当前系统中所有可用串口的信息列表
`QList<qint32> standardBaudRates()`	返回系统支持的标准波特率列表（单位：bps）

每个 QSerialPortInfo 对象代表一个具体的串口设备，其成员函数可获取该设备的详细信息：

成员函数	说明
`portName()`	串口名称（如 `COM1`、`/dev/ttyUSB0`），打开串口时必须使用此值
`description()`	设备描述文字，适合显示给用户
`manufacturer()`	制造商名称
`systemLocation()`	系统路径（不同平台格式不同）
`vendorIdentifier()`	USB 设备的供应商 ID（VID），仅 USB 设备有效
`productIdentifier()`	USB 设备的产品 ID（PID）
`serialNumber()`	设备序列号（若有）
`hasVendorIdentifier()` / `hasProductIdentifier()`	判断是否存在 VID/PID（虚拟串口通常没有）
`isNull()`	判断串口是否为空（无效）
`swap()`	交换两个 `QSerialPortInfo` 对象的内容

2. 跨平台注意事项

打开端口：始终使用 portName()，这是唯一跨平台可靠的标识符。
设备标识：如需持久化识别设备（如自动连接特定硬件），推荐组合使用 vendorIdentifier() + productIdentifier() + serialNumber()。虚拟串口或非 USB 串口可能缺少这些信息。
用户显示：description() 和 manufacturer() 提供了对用户友好的描述，适合在下拉列表中展示。
避免使用 systemLocation()：该值在不同平台差异很大，不宜作为设备标识。

3. 实战示例：枚举并显示串口信息

以下代码演示了如何获取所有可用串口，并输出其详细信息（实际应用中通常用于填充下拉列表）。

#include <QCoreApplication>
#include <QDebug>
#include <QSerialPortInfo>

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);

    qDebug() << "=== 可用串口列表 ===";
    const QList<QSerialPortInfo> ports = QSerialPortInfo::availablePorts();   // 值拷贝
    const QList<QSerialPortInfo> &ports = QSerialPortInfo::availablePorts();  // 引用绑定
    const auto ports = QSerialPortInfo::availablePorts(); //使用auto 简化书写 
    for (const QSerialPortInfo &info : ports) {
        qDebug() << "-----------------------------";
        qDebug() << "端口名:" << info.portName();
        qDebug() << "描述:" << info.description();
        qDebug() << "制造商:" << info.manufacturer();

        // 只有真实 USB 设备才存在 VID/PID，虚拟串口通常没有
        if (info.hasVendorIdentifier()) {
            qDebug() << "VID:" << QString::asprintf("0x%04X", info.vendorIdentifier());
            qDebug() << "PID:" << QString::asprintf("0x%04X", info.productIdentifier());
        }

        qDebug() << "系统位置:" << info.systemLocation();
        if (!info.serialNumber().isEmpty())
            qDebug() << "序列号:" << info.serialNumber();
    }

    qDebug() << "=== 标准波特率 ===";
    const auto baudRates = QSerialPortInfo::standardBaudRates();
    for (qint32 baud : baudRates) {
        qDebug() << baud;
    }

    return 0;
}

运行结果示例（Windows 环境）：

=== 可用串口列表 ===
-----------------------------
端口名: "COM1"
描述: "通信端口"
制造商: "(标准端口类型)"
系统位置: "\\\\.\\COM1"
-----------------------------
端口名: "COM2"
描述: "Virtual Serial Port (Eltima Software)"
制造商: "ELTIMA Software"
系统位置: "\\\\.\\COM2"
-----------------------------
端口名: "COM3"
描述: "Virtual Serial Port (Eltima Software)"
制造商: "ELTIMA Software"
系统位置: "\\\\.\\COM3"
=== 标准波特率 ===
110
300
...
115200

提示：QString::asprintf("0x%04X", value) 用于将整数格式化为 4 位十六进制字符串，方便查看 VID/PID。格式说明符 %04X 表示输出至少 4 位十六进制数字，不足左侧补 0。

二、QSerialPort

1.QSerialPort类介绍

QSerialPort 是访问具体某个串口的类，它可以设置串口通信的参数，打开串口后就可以读写串口数据。通过官方文档可以看出QSerialPort 的父类是QIODevice，所以它属于I/O设备类。

QSerialPort的基本使用流程：

设置串口通信参数

打开/关闭串口

进行串口数据的读/写

1.1 设置串口通信参数

串口通信参数主要只考虑波特率、数据位个数、停止位个数和奇偶校验位，在Qt中通过以下函数设置

参数	设置函数	获取函数
波特率	`bool setBaudRate(qint32 baudRate, Directions dir = AllDirections)`	`qint32 baudRate(Directions dir = AllDirections) const`
数据位	`bool setDataBits(QSerialPort::DataBits dataBits)`	`QSerialPort::DataBits dataBits() const`
停止位	`bool setStopBits(QSerialPort::StopBits stopBits)`	`QSerialPort::StopBits stopBits() const`
校验位	`bool setParity(QSerialPort::Parity parity)`	`QSerialPort::Parity parity() const`
流控	`bool setFlowControl(QSerialPort::FlowControl flow)`	`QSerialPort::FlowControl flowControl() const`

注意：波特率获取函数返回的是 qint32 类型，可直接用于显示或比较；其他参数返回对应的枚举类型。

1.1.1 波特率

设置函数：

bool setBaudRate(qint32 baudRate, QSerialPort::Directions directions = AllDirections);

baudRate：可直接指定数值（如 9600、115200），也可使用 QSerialPort 预定义的常量（如 QSerialPort::Baud115200）。
directions：默认 AllDirections，同时设置输入和输出方向。也可单独设置 Input 或 Output（很少用到）。

获取函数：

qint32 baudRate(QSerialPort::Directions directions = AllDirections) const;

返回当前波特率数值，可直接用于显示或比较。

1.2.1 数据位

设置函数：

bool setDataBits(QSerialPort::DataBits dataBits);

参数 dataBits 是 QSerialPort::DataBits 枚举类型。有两种使用方式：

// 方式一：使用枚举常量（推荐，可读性好）
comPort.setDataBits(QSerialPort::Data8);   // 8位数据

// 方式二：使用数值构造（等效）
comPort.setDataBits(QSerialPort::DataBits(8));   // 8位数据

获取函数：

QSerialPort::DataBits dataBits() const;

返回当前数据位的枚举值。可通过与枚举常量比较或转换为整型来获取实际位数：

if (comPort.dataBits() == QSerialPort::Data8) {
    qDebug() << "当前为 8 位数据";
}
int bits = static_cast<int>(comPort.dataBits());  // bits = 8

QSerialPort::DataBits 枚举常量与数值的对应关系如下：

Constant	Value	Description
`QSerialPort::Data5`	`5`	数据帧里一个字符的数据位数为5
`QSerialPort::Data6`	`6`	数据帧里一个字符的数据位数为6
`QSerialPort::Data7`	`7`	数据帧里一个字符的数据位数为7
`QSerialPort::Data8`	`8`	数据帧里一个字符的数据位数为8

1.3.1 停止位

设置函数：

bool setStopBits(QSerialPort::StopBits stopBits);

两种使用方式：

// 方式一：使用枚举常量
comPort.setStopBits(QSerialPort::OneStop);   // 1个停止位

// 方式二：使用数值构造
comPort.setStopBits(QSerialPort::StopBits(1));   // 1个停止位

获取函数：

QSerialPort::StopBits stopBits() const;

返回停止位枚举值，可通过与枚举常量比较或转换为整型：

if (comPort.stopBits() == QSerialPort::OneStop) {
    qDebug() << "停止位为 1";
}
int stop = static_cast<int>(comPort.stopBits());  // stop = 1

QSerialPort::StopBits 枚举常量与数值的对应关系如下：

Constant	Value	Description
`QSerialPort::OneStop`	`1`	1个停止位。
`QSerialPort::OneAndHalfStop`	`3`	表示 1.5 个停止位。
`QSerialPort::TwoStop`	`2`	2个停止位。

1.4.1 校验位

设置函数：

bool setParity(QSerialPort::Parity parity);

两种使用方式：

// 方式一：使用枚举常量
comPort.setParity(QSerialPort::NoParity);   // 无校验

// 方式二：使用数值构造
comPort.setParity(QSerialPort::Parity(0));   // 无校验

获取函数：

QSerialPort::Parity parity() const;

返回校验位枚举值，可通过与枚举常量比较或转换为整型：

if (comPort.parity() == QSerialPort::NoParity) {
    qDebug() << "无校验";
}
int parityVal = static_cast<int>(comPort.parity());  // parityVal = 0

QSerialPort::Parity 枚举常量与数值的对应关系如下：

Constant	Value	Description
`QSerialPort::NoParity`	`0`	无校验
`QSerialPort::EvenParity`	`2`	偶校验
`QSerialPort::OddParity`	`3`	奇校验
`QSerialPort::SpaceParity`	`4`	校验位始终为0
`QSerialPort::MarkParity`	`5`	校验位始终为1

💡注意：在串口通信中通常默认使用 8个数据位，1个停止位，无奇偶校验位。

1.5.1 设置示例

以下代码展示了两种设置串口参数的方式，两者效果完全相同：

方式一：使用枚举常量（推荐）

QSerialPort comPort;
comPort.setPortName("COM3");
comPort.setBaudRate(QSerialPort::Baud115200);      // 预定义常量
comPort.setDataBits(QSerialPort::Data8);           // 枚举常量
comPort.setStopBits(QSerialPort::OneStop);         // 枚举常量
comPort.setParity(QSerialPort::NoParity);          // 枚举常量

方式二：使用数值构造

QSerialPort comPort;
comPort.setPortName("COM3");
comPort.setBaudRate(115200);                       // 直接数值
comPort.setDataBits(QSerialPort::DataBits(8));     // 数值构造
comPort.setStopBits(QSerialPort::StopBits(1));     // 数值构造
comPort.setParity(QSerialPort::Parity(0));         // 数值构造

两种方式完全等效，可以根据代码风格选择任一种。通常推荐使用枚举常量，因为可读性更好；而数值构造在某些需要动态设置参数的场景下更为灵活。

1.2 打开串口

void setPort(const QSerialPortInfo &serialPortInfo) //设置串口，通过serialPortInfo 设置，
void setPortName(const QString &name) //设置串口，通过串口名
virtual void close() override //关闭
virtual bool open(QIODeviceBase::OpenMode mode) override //打开

其中函数setPort()以一个QSerialPortInfo 类型变量作为参数。setPortName()以串口名称作为参数，串口名称来自**QSerialPortInfo::portName()**函数的返回值。

使用open()打开一个串口，参数mode设置打开的模式，只能设置为QIODeviceBase::ReadOnly、 QIODeviceBase::WriteOnly 或 QIODeviceBase::ReadWrite，不能设置为其他模式。

注意，串口总是以独占方式打开的，也就是其他进程或线程无法访问一个已经被打开的串口。

串口使用结束后，不再需要使用串口通信时，要调用函数close()关闭串口。

1.3 数据读写

QSerialPort 支持 Qt 标准的 I/O 接口：

写数据：write(const QByteArray &data) 返回实际写入的字节数。
读数据：readAll() 读取所有可用数据，或使用 read(char *data, qint64 maxSize) 指定读取长度。

接收数据：串口有数据到达时会发射 readyRead() 信号，通常在此信号对应的槽函数中读取数据。

发送数据：直接调用 write()，无需等待信号。

注意：write() 只是将数据放入系统缓冲区，并不保证数据立即发出。如需确保数据发送完成，可调用 flush() 或 waitForBytesWritten()。

1.3 数据读写

打开串口后，就可以通过 QSerialPort 的读写函数进行数据收发。Qt 提供了**异步（非阻塞）和同步（阻塞）**两种方式。在 GUI 程序中推荐使用异步方式，避免界面卡顿；在非 GUI 程序或独立线程中可使用同步方式。

1.3.1 异步读写方式

异步方式下，读写操作立即返回，数据收发完成后通过信号通知应用程序。常用函数和信号如下：

类别	函数/信号	说明
读相关	`qint64 bytesAvailable()`	返回接收缓冲区中等待读取的字节数
	`QByteArray read(qint64 maxSize)`	读取最多 `maxSize` 个字节
	`QByteArray readAll()`	读取缓冲区内的全部数据
	`bool canReadLine()`	判断是否有完整的行数据（以换行符结束）
	`QByteArray readLine(qint64 maxSize = 0)`	读取一行数据，最多 `maxSize` 字节
写相关	`qint64 write(const char *data, qint64 maxSize)`	将 `data` 的前 `maxSize` 字节写入串口
	`qint64 write(const char *data)`	写入以 `\0` 结尾的字符串
	`qint64 write(const QByteArray &data)`	写入字节数组
信号	`void readyRead()`	接收缓冲区有新数据时发射
	`void bytesWritten(qint64 bytes)`	发送缓冲区的数据实际写入串口后发射

数据接收：当串口有数据到达时，QSerialPort 会发射 readyRead() 信号。通常在该信号对应的槽函数中调用 read() 或 readAll() 读取数据。

connect(serial, &QSerialPort::readyRead, this, &MyClass::onReadyRead);

void MyClass::onReadyRead()
{
    QByteArray data = serial->readAll();  // 读取所有可用数据
    // 处理数据...
}

注意：readyRead() 信号不会在每个字节到达时都发射，而是在收到一定量数据或数据流稳定后发射。因此，下位机编程时也应避免逐字节发送，建议攒够一批数据再发送，便于上位机处理。

数据发送：调用 write() 函数将数据放入发送缓冲区，函数立即返回，不会等待数据实际发送完毕。当数据真正通过串口发出后，会发射 bytesWritten() 信号（如果需要确认发送完成，可连接该信号）。

QByteArray sendData = "Hello\n";
qint64 written = serial->write(sendData);
if (written == sendData.size()) {
    // 数据已放入发送缓冲区，发送完成后会发射 bytesWritten()
}

1.3.2 同步（阻塞）读写方式

QSerialPort 提供了两个阻塞式等待函数，用于同步等待数据发送或接收完成：

bool waitForBytesWritten(int msecs = 30000);  // 最多等待 msecs 毫秒，直到数据发送完毕
bool waitForReadyRead(int msecs = 30000);     // 最多等待 msecs 毫秒，直到有数据可读

waitForBytesWritten() 会阻塞当前线程，直到发送缓冲区中的数据全部写入串口（即 bytesWritten 信号发射）或超时。
waitForReadyRead() 会阻塞当前线程，直到接收缓冲区中有新数据到达（即 readyRead 信号发射）或超时。

使用示例：

serial->write("AT\r\n");
if (serial->waitForBytesWritten(1000)) {
    qDebug() << "数据已发送";
}

if (serial->waitForReadyRead(2000)) {
    QByteArray response = serial->readAll();
    qDebug() << "接收到响应:" << response;
}

重要提示：这两个函数会阻塞当前线程的事件循环。如果在 GUI 线程中调用，可能导致界面无响应。因此，阻塞式读写应在非 GUI 线程（如 QThread）中使用，或仅在控制台程序中使用。

1.3.3 选择建议

应用场景	推荐方式	说明
GUI 程序	异步（信号槽）	避免界面卡顿，程序响应性好
控制台程序/后台服务	同步（阻塞）	代码逻辑简单，易于理解
需要实时性/频繁收发	异步 + 多线程	可将串口操作放在独立线程，主线程保持响应

GitHub关闭AI数据训练

Fri, 27 Mar 2026 00:00:00 GMT

GitHub关闭AI数据训练

GitHub 这次的政策调整核心就是：从 2026 年 4 月 24 日起，你的 Copilot 交互数据会被默认拿去训练 AI，除非你手动关闭。

最关键的一点是，这个设置 默认是开启的，如果你什么都不做，4 月 24 日之后你的数据就会自动被用于训练。

如何关闭数据收集

操作非常简单，跟着这几步走就行：

登录你的 GitHub 账号。
点击右上角头像，进入 Settings (设置)。
在左侧菜单栏找到并点击 Copilot。
在页面中找到 Privacy (隐私) 这一部分。
你会看到一个选项："Allow GitHub to use my data for AI model training" (允许 GitHub 使用我的数据进行 AI 模型训练)。点击旁边的下拉菜单，把它改为 "Disabled" (禁用) 。

如果你有多个 GitHub 账号，记得对每一个账号都重复一次上述操作。

关于这次新规，你可能关心的几个细节

谁受影响？谁豁免？
- 受影响：如果你用的是 Copilot Free (免费版)、Pro (个人专业版) 或 Pro+，那么新规对你生效，默认会被收集数据。
- 豁免：企业用户 (Copilot Business 和 Enterprise)、学生和教师不在这次新政的范围内，他们的数据不会被用于训练。
什么数据会被收集？ 不仅仅是代码片段。只要你使用 Copilot，它可能会收集：
- 你输入的 提示词 (Prompts) 和 Copilot 给出的 输出建议。
- 光标周围的 代码上下文、文件名、仓库结构。
- 你对建议的反馈 (比如点👍或👎)。
我的私有仓库安全吗？ 情况比较复杂。GitHub 强调，它们不会去扫描和训练你放在仓库里"静态"的私有代码。但是，一旦你在私有仓库里打开了 Copilot 并进行交互，这次对话产生的提示词和生成的代码片段就会被收集。

简单来说，只要你用 Copilot，数据就可能被采集，跟你写代码的仓库是公开还是私有无关。

Mihomo 配置文件详细介绍

Fri, 13 Mar 2026 00:00:00 GMT

Mihomo 配置文件详细介绍

⚠️ 合规使用声明 ：本教程仅用于内网流量调试、开发测试及合法网络管理场景，禁止用于任何违法用途。请遵守当地法律法规。

一、配置文件概览

本配置文件是一个功能全面的 Mihomo 配置，适用于作为网关或桌面代理使用。它集成了以下核心特性：

基础代理服务：混合端口、HTTP/SOCKS5 代理，支持 IPv6 和局域网共享。
TUN 透明代理：实现系统全局代理，无需每个应用单独配置。
DNS 配置：使用 Fake-IP 模式，智能分流国内外域名解析。
内置地理数据源：通过 geodata-mode 自动下载 GeoIP/GeoSite 数据库，用于域名和 IP 规则匹配。
流量嗅探：识别未加密流量中的域名，增强分流准确性。
代理提供者：支持多个订阅源，并可自动更新节点列表。
广告拦截：通过 rule-providers 拉取广告规则集，优先拒绝广告请求。
灵活的代理分组：包括手动选择地区分组、自动优选、负载均衡、故障转移等多种策略，并支持选择节点来源（所有提供者或指定提供者）。
Web 管理面板：自动下载并启用 metacubexd 面板，方便通过浏览器管理。

二、配置模块详解

1. 基础配置

mixed-port: 7890
ipv6: true
allow-lan: true
unified-delay: false
tcp-concurrent: true
external-controller: 0.0.0.0:9090
external-ui: ui
external-ui-url: "https://ghproxy.cn/github.com/MetaCubeX/metacubexd/archive/gh-pages.zip"
find-process-mode: strict
global-client-fingerprint: chrome
profile:
  store-selected: true
  store-fake-ip: true

mixed-port：同时支持 HTTP 和 SOCKS5 的混合代理端口。
ipv6：启用 IPv6 支持。
allow-lan：允许局域网其他设备使用此代理。
unified-delay：关闭统一延迟测试，保持各节点独立延迟数据。
tcp-concurrent：启用 TCP 并发，提升多连接场景性能。
external-controller：RESTful API 监听地址，0.0.0.0:9090 表示监听所有接口，允许局域网访问面板。如需仅本机访问，可改为 127.0.0.1:9090。
external-ui 和 external-ui-url：自动下载并挂载 Web 面板（metacubexd），访问 http://<设备IP>:9090/ui 即可打开面板。
find-process-mode：进程查找模式，strict 提高匹配准确性。
global-client-fingerprint：设置全局 TLS 指纹，伪装成 Chrome 浏览器，减少 TLS 指纹识别风险。
profile：保存用户手动选择的节点和 Fake-IP 映射，重启后恢复。

2. 内置地理数据源

geodata-mode: true
geox-url:
  geoip: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip-lite.dat"
  geosite: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat"
  mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/country-lite.mmdb"
  asn: "https://github.com/xishang0128/geoip/releases/download/latest/GeoLite2-ASN.mmdb"

geodata-mode：启用内置地理数据模式，规则中的 GEOIP 和 GEOSITE 将从配置的 URL 下载数据库。
geox-url：指定各数据库的下载地址，Mihomo 会自动下载并缓存。geoip-lite.dat 为精简版 IP 归属地数据库，geosite.dat 为域名分类数据库，country-lite.mmdb 为 MaxMind 格式的 IP 数据库，GeoLite2-ASN.mmdb 为 ASN 信息数据库。

3. 流量嗅探

sniffer:
  enable: true
  sniff:
    HTTP:
      ports: [80, 8080-8880]
      override-destination: true
    TLS:
      ports: [443, 8443]
    QUIC:
      ports: [443, 8443]
  skip-domain:
    - "Mijia Cloud"
    - "+.push.apple.com"

enable：开启流量嗅探，能够从 HTTP、TLS 和 QUIC 流量中提取域名，用于分流决策。
sniff：定义各协议监听的端口。
override-destination：当嗅探到域名后，使用该域名替代原始目标地址进行规则匹配。
skip-domain：跳过对指定域名的嗅探（如小米云、苹果推送），避免干扰。

4. TUN 透明代理

tun:
  enable: true
  stack: mixed
  dns-hijack:
    - "any:53"
    - "tcp://any:53"
  auto-route: true
  auto-redirect: true
  auto-detect-interface: true

enable：启用 TUN 虚拟网卡，实现全局代理。
stack：网络栈，mixed 同时支持 TCP 和 UDP。
dns-hijack：劫持所有发往 53 端口的 DNS 请求，强制使用 Mihomo 内部 DNS。
auto-route：自动添加路由表，将流量导向 TUN 设备。
auto-redirect：自动配置 iptables 规则（仅 Linux），实现透明代理。
auto-detect-interface：自动检测默认出口网卡。

5. DNS 配置

dns:
  enable: true
  ipv6: true
  respect-rules: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - "*"
    - "+.lan"
    - "+.local"
    - "+.market.xiaomi.com"
  nameserver:
    - https://120.53.53.53/dns-query
    - https://223.5.5.5/dns-query
  proxy-server-nameserver:
    - https://120.53.53.53/dns-query
    - https://223.5.5.5/dns-query
  nameserver-policy:
    "geosite:cn,private":
      - https://120.53.53.53/dns-query
      - https://223.5.5.5/dns-query
    "geosite:geolocation-!cn":
      - "https://dns.cloudflare.com/dns-query"
      - "https://dns.google/dns-query"

enable：启用内置 DNS 服务器。
respect-rules：DNS 查询结果将遵守分流规则。
enhanced-mode：fake-ip 模式，为每个域名分配一个假的 IP，减少真实 DNS 查询，提升隐私和速度。
fake-ip-filter：对这些域名不返回 Fake-IP，而是进行真实 DNS 查询。* 表示所有域名，但后续的 +.lan 等是排除项，即对 .lan、.local 等域名直接查询。
nameserver：默认 DNS 服务器（用于国内域名或未匹配策略的域名）。
proxy-server-nameserver：当使用代理节点进行 DNS 查询时使用的 DNS 服务器。
nameserver-policy：根据域名分类指定不同的 DNS 服务器。这里将中国域名和私有域名交给国内 DoH，非中国域名交给国外 DoH。

6. 代理提供者（订阅）

proxy-providers:
  机场A:
    type: http
    url: "YOUR_SUBSCRIPTION_URL_1"
    interval: 86400
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300
    override:
      additional-prefix: "[机场A]"
  机场B:
    ...

机场A/机场B：自定义的提供者名称，用于在分组中引用。
type：http 表示通过 HTTP/HTTPS 获取节点列表。
url：订阅链接，请替换为实际地址。
interval：更新间隔（秒），86400 为每天更新一次。
health-check：定期测试节点延迟，enable: true 启用，url 测试目标，interval 测试频率。
override：为从该提供者获取的每个节点名称添加前缀，便于识别来源。

7. 直连节点

proxies:
  - name: "直连"
    type: direct
    udp: true

定义一个直连节点，用于不走代理的流量。

8. 广告拦截规则集（rule-providers）

rule-providers:
  AD:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/AD.yaml"
    path: ./rules/AD.yaml
  ...

rule-providers：定义外部规则集提供者，用于动态更新规则。
AD、EasyList 等：规则集名称，在 rules 中用 RULE-SET,名称 引用。
type：http 表示通过 HTTP 获取规则文件。
behavior：规则行为，domain 表示匹配域名。
url：规则文件的下载地址。
path：本地缓存路径。
interval：更新间隔（秒），86400 每天更新一次。

这些广告规则集用于在规则匹配初期拒绝广告请求。

9. 代理分组

代理分组是分流策略的核心，本配置提供了多种类型的分组。

9.1 顶级手动分组（默认）

- name: 默认
  type: select
  proxies:
    - 自动选择
    - 全部节点
    - 负载均衡(散列)
    - 负载均衡(轮询)
    - 故障转移
    - 直连
    - 香港
    - 台湾
    - 日本
    - 新加坡
    - 美国
    - 其它地区

type: select：手动选择模式，用户可在面板中从列出的代理中任选一个。
proxies：列出了可供选择的子分组和直连节点，作为最终出口的候选。

9.2 地区分组（手动选择，带正则过滤）

例如香港分组：

- name: 香港
  type: select
  # include-all: true
  # use:
  #   - 机场A
  #   - 机场B
  filter: "(?i)港|hk|hongkong|hong kong"
  exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

type: select：手动选择节点。
节点来源：可以通过 include-all: true 从所有代理提供者中筛选，也可以通过 use 指定只从某些提供者中筛选。两者只能选其一，本配置中已注释掉两种方式，您需要根据需求取消对应行的注释。
- 若取消注释 include-all: true，则从所有提供者中筛选。
- 若取消注释 use，则只从列出的提供者（如机场A、机场B）中筛选。
filter：正则表达式，匹配节点名称中包含“港”、“hk”等关键词的节点。
exclude-filter：排除包含回国、国内省市、运营商等关键词的节点，确保不选中回国线。

其他地区分组（台湾、日本、美国、新加坡、其它地区）类似，正则表达式已针对各区域调整。

9.3 自动优选分组

- name: 自动选择
  type: url-test
  # include-all: true
  # use:
  #   - 机场A
  #   - 机场B
  tolerance: 10
  exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

type: url-test：自动测试节点延迟，选择延迟最低的节点。
tolerance：延迟差在 10ms 内的节点视为同等，避免频繁切换。
同样支持 include-all 或 use 选择节点来源。

9.4 全部节点

- name: 全部节点
  type: select
  # include-all: true
  # use:
  #   - 机场A
  #   - 机场B

手动选择所有节点中的具体某个节点，不经过正则过滤。

9.5 负载均衡分组

- name: 负载均衡(散列)
  type: load-balance
  # include-all: true
  # use:
  #   - 机场A
  #   - 机场B
  strategy: consistent-hashing
- name: 负载均衡(轮询)
  type: load-balance
  strategy: round-robin

type: load-balance：负载均衡策略。
strategy：consistent-hashing 一致性哈希，适合需要保持会话一致性的场景；round-robin 轮询，轮流使用节点。

9.6 故障转移

- name: 故障转移
  type: fallback
  # include-all: true
  # use:
  #   - 机场A
  #   - 机场B

type: fallback：按顺序尝试节点，失败时切换到下一个。

9.7 国内流量分组

- name: 国内
  type: select
  proxies:
    - 直连
    - 默认
    - 自动选择
    - 香港
    - 台湾
    - 日本
    - 新加坡
    - 美国
    - 其它地区
    - 全部节点

专用于国内域名，默认选项为 直连，但用户可以手动切换为其他分组。

9.8 服务分组

为各常用服务（Google、Telegram、Twitter 等）定义了独立分组，大部分为 select 类型，允许用户手动选择出口。其中 Telegram 分组为 url-test 类型，并配有复杂的正则过滤，自动优选境外节点。

- name: Telegram
  type: url-test
  # include-all: true
  # use:
  #   - 机场A
  #   - 机场B
  url: "https://www.gstatic.com/generate_204"
  interval: 300
  tolerance: 50
  filter: "(?i)(港|hk|hongkong|hong kong|台|tw|taiwan|日|jp|japan|美|us|unitedstates|united states|新|sg|singapore)"
  exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

url：测速目标。
interval：测速间隔。
tolerance：延迟容忍度。
filter/exclude-filter：筛选境外节点，排除回国节点。

10. 规则（rules）

规则按照从上到下的顺序匹配，匹配即停止。本配置的规则顺序为：

广告拦截：使用 RULE-SET 引用广告规则集，匹配到的请求直接 REJECT。
私有 IP 直连：GEOIP,private,直连,no-resolve，所有私有 IP 地址（如 192.168.x.x）直接连接。
域名规则：使用 GEOSITE 匹配各服务域名，指向对应的服务分组。例如 GEOSITE,google,Google 将 Google 域名指向 Google 分组。
国内域名：GEOSITE,cn,国内，将中国域名指向“国内”分组（默认直连）。
非中国域名：GEOSITE,geolocation-!cn,其他，将非中国域名指向“其他”分组。
IP 规则：GEOIP,CN,国内,no-resolve，将中国 IP 指向“国内”分组。
最终兜底：MATCH,其他，所有未匹配流量最终走“其他”分组。

三、如何选择节点来源

在代理分组中，我们提供了两种方式来指定节点来源：

include-all: true：从所有已定义的 proxy-providers 中筛选节点。适合希望合并多个订阅源的情况。
use：列出特定的提供者名称，只从这些提供者中筛选节点。适合只想使用部分订阅源的情况。

操作方式：在分组配置中，找到对应的注释行，取消注释所需方式的行，并注释掉另一种方式。例如：

- name: 香港
  type: select
  include-all: true   # 取消注释此行，表示从所有提供者中筛选
  # use:              # 注释掉 use 块，表示不使用指定提供者
  #   - 机场A
  #   - 机场B
  filter: ...

或者

- name: 香港
  type: select
  # include-all: true   # 注释掉 include-all
  use:                  # 取消注释 use 块
    - 机场A
    - 机场B
  filter: ...

注意：include-all 和 use 是互斥的，只能选择其一。

四、广告规则集的更新与自定义

广告规则集通过 rule-providers 定义，配置如下：

rule-providers:
  AD:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/AD.yaml"
    path: ./rules/AD.yaml

每个规则集每天（86400 秒）自动从指定 URL 拉取最新版本，并缓存到本地 ./rules/ 目录下。
如需添加自定义广告规则，可以新建一个 rule-provider，指向自己维护的规则文件，或者在本地 path 文件中手动添加规则。
在 rules 部分，使用 RULE-SET,名称,REJECT 即可引用该规则集进行广告拦截。

五、使用注意事项

替换订阅链接：请务必将 YOUR_SUBSCRIPTION_URL_1 和 YOUR_SUBSCRIPTION_URL_2 替换为您的实际订阅地址。
节点来源选择：根据您的需求，在每个需要筛选节点的分组中正确选择 include-all 或 use，并确保提供者名称与 proxy-providers 中定义的一致。
正则表达式：地区分组和服务分组中的正则表达式基于常见节点命名习惯编写，可能无法覆盖所有情况。如果某些节点未被正确归类，可自行调整正则。
首次启动：首次启动时会自动下载 GeoIP/GeoSite 数据库、Web 面板以及广告规则集，请确保网络畅通。如果下载失败，可手动下载对应文件放入指定路径。
Web 面板访问：启动后，通过浏览器访问 http://<设备IP>:9090/ui 即可打开面板。如需从外网访问，请确保防火墙允许 9090 端口，并注意安全。
TUN 模式依赖：TUN 模式需要 root/管理员权限，并确保系统支持（Linux 需开启 net.ipv4.ip_forward）。

六、故障排查

查看日志：sudo journalctl -u Mihomo -f（如果使用 systemd 管理）。
检查配置文件语法：/usr/local/bin/Mihomo -t -d /etc/Mihomo。
确认订阅链接是否可访问，规则文件 URL 是否有效。
如果某些网站无法访问，尝试调整规则顺序或修改对应分组策略。

七、完整配置文件参考

1.基于内置地理数据的 Mihomo 配置文件

# ========== 基础配置 ==========
mixed-port: 7890
ipv6: true
allow-lan: true
unified-delay: false
tcp-concurrent: true
external-controller: 0.0.0.0:9090      # 允许局域网访问面板
external-ui: ui
external-ui-url: "https://ghproxy.cn/github.com/MetaCubeX/metacubexd/archive/gh-pages.zip"

find-process-mode: strict
global-client-fingerprint: chrome

profile:
  store-selected: true
  store-fake-ip: true

# ========== 内置地理数据源 ==========
geodata-mode: true
geox-url:
  geoip: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geoip-lite.dat"
  geosite: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/geosite.dat"
  mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/download/latest/country-lite.mmdb"
  asn: "https://github.com/xishang0128/geoip/releases/download/latest/GeoLite2-ASN.mmdb"

# ========== 流量嗅探 ==========
sniffer:
  enable: true
  sniff:
    HTTP:
      ports: [80, 8080-8880]
      override-destination: true
    TLS:
      ports: [443, 8443]
    QUIC:
      ports: [443, 8443]
  skip-domain:
    - "Mijia Cloud"
    - "+.push.apple.com"

# ========== TUN 透明代理 ==========
tun:
  enable: true
  stack: mixed
  dns-hijack:
    - "any:53"
    - "tcp://any:53"
  auto-route: true
  auto-redirect: true
  auto-detect-interface: true

# ========== DNS 配置 ==========
dns:
  enable: true
  ipv6: true
  respect-rules: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - "*"
    - "+.lan"
    - "+.local"
    - "+.market.xiaomi.com"
  nameserver:
    - https://120.53.53.53/dns-query
    - https://223.5.5.5/dns-query
  proxy-server-nameserver:
    - https://120.53.53.53/dns-query
    - https://223.5.5.5/dns-query
  nameserver-policy:
    "geosite:cn,private":
      - https://120.53.53.53/dns-query
      - https://223.5.5.5/dns-query
    "geosite:geolocation-!cn":
      - "https://dns.cloudflare.com/dns-query"
      - "https://dns.google/dns-query"

# ========== 代理提供者（订阅） ==========
proxy-providers:
  机场A:
    type: http
    url: "YOUR_SUBSCRIPTION_URL_1"          # 替换为实际订阅链接
    interval: 86400
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300
    override:
      additional-prefix: "[机场A]"
  机场B:
    type: http
    url: "YOUR_SUBSCRIPTION_URL_2"          # 替换为实际订阅链接
    interval: 86400
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300
    override:
      additional-prefix: "[机场B]"

# ========== 直连节点 ==========
proxies:
  - name: "直连"
    type: direct
    udp: true

# ========== 广告拦截规则集（YAML 格式，保留） ==========
rule-providers:
  AD:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/AD.yaml"
    path: ./rules/AD.yaml
  EasyList:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/EasyList.yaml"
    path: ./rules/EasyList.yaml
  EasyListChina:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/EasyListChina.yaml"
    path: ./rules/EasyListChina.yaml
  EasyPrivacy:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/EasyPrivacy.yaml"
    path: ./rules/EasyPrivacy.yaml
  ProgramAD:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/ProgramAD.yaml"
    path: ./rules/ProgramAD.yaml

# ========== 代理分组 ==========
proxy-groups:
  # 顶级手动分组
  - name: 默认
    type: select
    proxies:
      - 自动选择
      - 全部节点
      - 负载均衡(散列)
      - 负载均衡(轮询)
      - 故障转移
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区

  # 地区分组（手动选择，带复杂正则过滤）
  # 选择使用 include-all: true（所有提供者）或 use（指定提供者）
  - name: 香港
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)港|hk|hongkong|hong kong"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: 台湾
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)台|tw|taiwan"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: 日本
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)日|jp|japan"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: 美国
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)美|us|unitedstates|united states"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: 新加坡
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)(新|sg|singapore)"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: 其它地区
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)^(?!.*(?:🇭🇰|🇯🇵|🇺🇸|🇸🇬|🇨🇳|港|hk|hongkong|台|tw|taiwan|日|jp|japan|新|sg|singapore|美|us|unitedstates)).*"

  # 自动优选分组
  - name: 自动选择
    type: url-test
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    tolerance: 10
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  # 全部节点（手动选择具体节点）
  - name: 全部节点
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B

  # 负载均衡分组
  - name: 负载均衡(散列)
    type: load-balance
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    strategy: consistent-hashing

  - name: 负载均衡(轮询)
    type: load-balance
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    strategy: round-robin

  # 故障转移
  - name: 故障转移
    type: fallback
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B

  # 国内流量分组（默认直连，但可手动切换）
  - name: 国内
    type: select
    proxies:
      - 直连
      - 默认
      - 自动选择
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  # ---- 服务分组 ----
  - name: Google
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: Telegram
    type: url-test
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50
    filter: "(?i)(港|hk|hongkong|hong kong|台|tw|taiwan|日|jp|japan|美|us|unitedstates|united states|新|sg|singapore)"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: Twitter
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: 哔哩哔哩
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: 巴哈姆特
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: YouTube
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: NETFLIX
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: Spotify
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: Github
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: 其他
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

# ========== 规则 ==========
rules:
  # 广告拦截（优先）
  - RULE-SET,AD,REJECT
  - RULE-SET,EasyList,REJECT
  - RULE-SET,EasyListChina,REJECT
  - RULE-SET,EasyPrivacy,REJECT
  - RULE-SET,ProgramAD,REJECT

  # 私有 IP 直连
  - GEOIP,private,直连,no-resolve

  # 域名规则（使用内置 geosite）
  - GEOSITE,google,Google
  - GEOSITE,telegram,Telegram
  - GEOSITE,twitter,Twitter
  - GEOSITE,youtube,YouTube
  - GEOSITE,bilibili,哔哩哔哩
  - GEOSITE,bahamut,巴哈姆特
  - GEOSITE,netflix,NETFLIX
  - GEOSITE,spotify,Spotify
  - GEOSITE,github,Github
  - GEOSITE,cn,国内
  - GEOSITE,geolocation-!cn,其他

  # IP 规则（仅保留国家/地区级别）
  - GEOIP,CN,国内,no-resolve

  # 最终兜底
  - MATCH,其他

2.基于外部 rule-providers 的 Mihomo 配置文件

# ========== 基础配置 ==========
mixed-port: 7890
ipv6: true
allow-lan: true
unified-delay: false
tcp-concurrent: true
external-controller: 0.0.0.0:9090      # 允许局域网访问面板
external-ui: ui
external-ui-url: "https://ghproxy.cn/github.com/MetaCubeX/metacubexd/archive/gh-pages.zip"

find-process-mode: strict
global-client-fingerprint: chrome

profile:
  store-selected: true
  store-fake-ip: true

# ========== 流量嗅探 ==========
sniffer:
  enable: true
  sniff:
    HTTP:
      ports: [80, 8080-8880]
      override-destination: true
    TLS:
      ports: [443, 8443]
    QUIC:
      ports: [443, 8443]
  skip-domain:
    - "Mijia Cloud"
    - "+.push.apple.com"

# ========== TUN 透明代理 ==========
tun:
  enable: true
  stack: mixed
  dns-hijack:
    - "any:53"
    - "tcp://any:53"
  auto-route: true
  auto-redirect: true
  auto-detect-interface: true

# ========== DNS 配置 ==========
dns:
  enable: true
  ipv6: true
  respect-rules: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - "*"
    - "+.lan"
    - "+.local"
    - "+.market.xiaomi.com"
  nameserver:
    - https://120.53.53.53/dns-query
    - https://223.5.5.5/dns-query
  proxy-server-nameserver:
    - https://120.53.53.53/dns-query
    - https://223.5.5.5/dns-query
  nameserver-policy:
    "rule-set:cn_domain,private_domain":
      - https://120.53.53.53/dns-query
      - https://223.5.5.5/dns-query
    "rule-set:geolocation-!cn":
      - "https://dns.cloudflare.com/dns-query"
      - "https://dns.google/dns-query"

# ========== 代理提供者（订阅） ==========
proxy-providers:
  机场A:
    type: http
    url: "YOUR_SUBSCRIPTION_URL_1"          # 替换为实际订阅链接
    interval: 86400
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300
    override:
      additional-prefix: "[机场A]"
  机场B:
    type: http
    url: "YOUR_SUBSCRIPTION_URL_2"          # 替换为实际订阅链接
    interval: 86400
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300
    override:
      additional-prefix: "[机场B]"

# ========== 直连节点 ==========
proxies:
  - name: "直连"
    type: direct
    udp: true

# ========== 规则集提供者（使用锚点简化） ==========
rule-anchor:
  ip: &ip {type: http, interval: 86400, behavior: ipcidr, format: mrs}
  domain: &domain {type: http, interval: 86400, behavior: domain, format: mrs}

rule-providers:
  # ---- 广告拦截（YAML 格式，可自行替换为 MRS） ----
  AD:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/AD.yaml"
    path: ./rules/AD.yaml
  EasyList:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/EasyList.yaml"
    path: ./rules/EasyList.yaml
  EasyListChina:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/EasyListChina.yaml"
    path: ./rules/EasyListChina.yaml
  EasyPrivacy:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/EasyPrivacy.yaml"
    path: ./rules/EasyPrivacy.yaml
  ProgramAD:
    type: http
    interval: 86400
    behavior: domain
    url: "https://raw.githubusercontent.com/earoftoast/clash-rules/main/ProgramAD.yaml"
    path: ./rules/ProgramAD.yaml

  # ---- 常用域名规则集（MRS 格式） ----
  private_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/private.mrs"
  cn_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/cn.mrs"
  google_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/google.mrs"
  telegram_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/telegram.mrs"
  twitter_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/twitter.mrs"
  youtube_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/youtube.mrs"
  bilibili_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/bilibili.mrs"
  bahamut_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/bahamut.mrs"
  netflix_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/netflix.mrs"
  spotify_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/spotify.mrs"
  github_domain:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/github.mrs"
  geolocation-!cn:
    <<: *domain
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geosite/geolocation-!cn.mrs"

  # ---- IP 规则集（MRS 格式） ----
  private_ip:
    <<: *ip
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geoip/private.mrs"
  cn_ip:
    <<: *ip
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geoip/cn.mrs"
  google_ip:
    <<: *ip
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geoip/google.mrs"
  telegram_ip:
    <<: *ip
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geoip/telegram.mrs"
  twitter_ip:
    <<: *ip
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geoip/twitter.mrs"
  netflix_ip:
    <<: *ip
    url: "https://ghproxy.cn/https://raw.github.com/MetaCubeX/meta-rules-dat/meta/geo/geoip/netflix.mrs"

# ========== 代理分组 ==========
proxy-groups:
  # 顶级手动分组
  - name: 默认
    type: select
    proxies:
      - 自动选择
      - 全部节点
      - 负载均衡(散列)
      - 负载均衡(轮询)
      - 故障转移
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区

  # 地区分组（手动选择，带复杂正则过滤）
  # 选择使用 include-all: true（所有提供者）或 use（指定提供者）
  - name: 香港
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)港|hk|hongkong|hong kong"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: 台湾
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)台|tw|taiwan"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: 日本
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)日|jp|japan"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: 美国
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)美|us|unitedstates|united states"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: 新加坡
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)(新|sg|singapore)"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: 其它地区
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    filter: "(?i)^(?!.*(?:🇭🇰|🇯🇵|🇺🇸|🇸🇬|🇨🇳|港|hk|hongkong|台|tw|taiwan|日|jp|japan|新|sg|singapore|美|us|unitedstates)).*"

  # 自动优选分组
  - name: 自动选择
    type: url-test
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    tolerance: 10
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  # 全部节点（手动选择具体节点）
  - name: 全部节点
    type: select
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B

  # 负载均衡分组
  - name: 负载均衡(散列)
    type: load-balance
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    strategy: consistent-hashing

  - name: 负载均衡(轮询)
    type: load-balance
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    strategy: round-robin

  # 故障转移
  - name: 故障转移
    type: fallback
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B

  # 国内流量分组（默认直连，但可手动切换）
  - name: 国内
    type: select
    proxies:
      - 直连
      - 默认
      - 自动选择
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  # ---- 服务分组 ----
  - name: Google
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: Telegram
    type: url-test
    # include-all: true
    # use:
    #   - 机场A
    #   - 机场B
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50
    filter: "(?i)(港|hk|hongkong|hong kong|台|tw|taiwan|日|jp|japan|美|us|unitedstates|united states|新|sg|singapore)"
    exclude-filter: "(?i)回国|安徽|北京|重庆|福建|甘肃|广东|广西|贵州|海南|河北|黑龙江|河南|湖北|湖南|吉林|江苏|江西|辽宁|内蒙古|宁夏|青海|山东|山西|陕西|上海|四川|天津|西藏|新疆|云南|浙江|官网|国内|国际|移动|联通|电信|cn|china"

  - name: Twitter
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: 哔哩哔哩
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: 巴哈姆特
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: YouTube
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: NETFLIX
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: Spotify
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: Github
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

  - name: 其他
    type: select
    proxies:
      - 默认
      - 自动选择
      - 直连
      - 香港
      - 台湾
      - 日本
      - 新加坡
      - 美国
      - 其它地区
      - 全部节点

# ========== 规则 ==========
rules:
  # 广告拦截（优先）
  - RULE-SET,AD,REJECT
  - RULE-SET,EasyList,REJECT
  - RULE-SET,EasyListChina,REJECT
  - RULE-SET,EasyPrivacy,REJECT
  - RULE-SET,ProgramAD,REJECT

  # 私有 IP 直连
  - RULE-SET,private_ip,直连,no-resolve

  # 域名规则
  - RULE-SET,google_domain,Google
  - RULE-SET,telegram_domain,Telegram
  - RULE-SET,twitter_domain,Twitter
  - RULE-SET,youtube_domain,YouTube
  - RULE-SET,bilibili_domain,哔哩哔哩
  - RULE-SET,bahamut_domain,巴哈姆特
  - RULE-SET,netflix_domain,NETFLIX
  - RULE-SET,spotify_domain,Spotify
  - RULE-SET,github_domain,Github
  - RULE-SET,cn_domain,国内
  - RULE-SET,geolocation-!cn,其他

  # IP 规则
  - RULE-SET,google_ip,Google,no-resolve
  - RULE-SET,telegram_ip,Telegram,no-resolve
  - RULE-SET,twitter_ip,Twitter,no-resolve
  - RULE-SET,netflix_ip,NETFLIX,no-resolve
  - RULE-SET,cn_ip,国内,no-resolve

  # 最终兜底
  - MATCH,其他

使用 Systemd 部署 Mihomo

Thu, 12 Mar 2026 00:00:00 GMT

使用 Systemd 部署 Mihomo

一、安装内核与准备配置

在将 mihomo 交给 systemd 管理前，需要先把它的"骨架"搭建好。

下载并安装 mihomo 内核：从 mihomo 的官方发布页面下载对应你系统架构（如 linux-amd64）的压缩包。解压后，将二进制文件复制到系统的程序目录并赋予执行权限：
```
# 假设你已经将文件解压并重命名为 mihomo
sudo cp mihomo /usr/local/bin/
sudo chmod +x /usr/local/bin/mihomo
```
创建配置目录和文件： mihomo 默认会从 /etc/mihomo 目录读取配置。
```
sudo mkdir -p /etc/mihomo
```
然后，你需要创建一个核心配置文件 /etc/mihomo/config.yaml 。你可以将从你的服务商获取的订阅链接内容，或一个基础的配置文件模板放入其中。

二、创建 systemd 配置文件

创建 systemd 配置文件 /etc/systemd/system/mihomo.service:

sudo vim /etc/systemd/system/mihomo.service

然后，粘贴以下配置内容：

[Unit]
Description=mihomo Daemon
# 等待网络完全就绪后再启动，避免启动时网络不可用
After=network-online.target
Wants=network-online.target

[Service]
# 以普通用户身份运行，最小权限原则
User=mihomo
Group=mihomo

# 资源限制
Type=simple
LimitNPROC=500
LimitNOFILE=1000000

# 官方推荐
#CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_TIME CAP_SYS_PTRACE CAP_DAC_READ_SEARCH CAP_DAC_OVERRIDE
#AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_TIME CAP_SYS_PTRACE CAP_DAC_READ_SEARCH CAP_DAC_OVERRIDE

# 限制：仅保留运行TUN模式和绑定低端口所必需的能力
# 移除了高危的 CAP_DAC_OVERRIDE, CAP_SYS_PTRACE 等
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE

# 启用一系列安全沙箱选项，进一步隔离服务
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
# 允许写入的数据目录（如缓存、持久化连接）
ReadWritePaths=/var/lib/mihomo
# 允许写入内核文件所在目录，以便面板能够更新内核
ReadWritePaths=/usr/local/bin
# 允许写入配置文件所在目录，以便面板能够更新配置
ReadWritePaths=/etc/mihomo
ProtectHome=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectControlGroups=yes

# 服务行为
Restart=always
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target

配置解读：

[Unit] 单元描述与依赖

配置项	设置值	作用/解释
`Description`	`mihomo Daemon`	服务的简要描述，便于管理员识别。
`After`	`network-online.target`	声明此服务应在网络完全就绪的 target 之后启动，避免启动时网络不可用导致失败。
`Wants`	`network-online.target`	表示希望 network-online.target 被激活，但并不严格要求其成功；通常与 `After` 配合使用以确保网络已配置好。

[Service] 服务运行定义

配置项	设置值	作用/解释
用户与组
`User`	`mihomo`	以非特权系统用户 `mihomo` 的身份运行服务，避免使用 root 账户，实现最小权限原则。
`Group`	`mihomo`	服务运行时所属的组，同样为非特权组。
服务类型与资源限制
`Type`	`simple`	默认类型，表示 `ExecStart` 启动的进程就是主进程，systemd 会将其作为服务的主控进程。
`LimitNPROC`	`500`	限制服务及其子进程的最大进程/线程数为 500。
`LimitNOFILE`	`1000000`	限制文件描述符数量为 100 万，满足高并发网络连接需求。
Linux Capabilities（能力集）
`CapabilityBoundingSet`	`CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE`	限制进程可拥有的能力边界，超出此集合的能力即使通过 `exec` 也无法获得。此处仅保留网络管理、原始套接字和绑定特权端口所需的能力。
`AmbientCapabilities`	同上	在 `exec` 后仍保留上述能力，使得非 root 用户启动的进程也能保持这些能力。
安全沙箱选项
`NoNewPrivileges`	`yes`	禁止进程及其子进程通过 `execve` 获得新特权（如通过 setuid 或文件系统能力），即使文件有 suid 位也无效，增强安全性。
`PrivateTmp`	`yes`	为服务创建独立的临时文件空间 `/tmp` 和 `/var/tmp`，与其他进程隔离，防止临时文件信息泄露。
`ProtectSystem`	`strict`	以最严格模式保护系统文件：将 `/usr`、`/boot`、`/etc` 挂载为只读，服务无法修改这些关键系统目录。
`ReadWritePaths`	`/var/lib/mihomo`	在 `ProtectSystem=strict` 下，允许服务对指定目录（如数据目录）拥有写入权限。
`ReadWritePaths`	`/usr/local/bin`	允许面板更新内核文件
`ProtectHome`	`yes`	将 `/home`、`/root` 和 `/run/user` 挂载为不可访问（返回空或隐藏），保护用户隐私数据。
`ProtectKernelTunables`	`yes`	禁止修改内核可调参数（`/sys/...`、`/proc/sys/...`），防止内核配置被篡改。
`ProtectKernelModules`	`yes`	禁止加载或卸载内核模块，防止内核模块攻击。
`ProtectControlGroups`	`yes`	禁止修改 cgroup（控制组）配置，防止资源隔离被破坏。
服务行为
`Restart`	`always`	无论退出原因（正常退出或异常崩溃），服务总是自动重启，确保高可用性。
`ExecStart`	`/usr/local/bin/mihomo -d /etc/mihomo`	启动 mihomo 主程序，`-d` 指定配置目录为 `/etc/mihomo`。
`ExecReload`	`/bin/kill -HUP $MAINPID`	当执行 `systemctl reload mihomo` 时，向主进程发送 HUP 信号，触发配置重载（需 mihomo 支持）。

[Install] 安装与自启

配置项	设置值	作用/解释
`WantedBy`	`multi-user.target`	表示该服务应在系统进入多用户运行级别（通常为正常启动后）时自动启动。

三、创建用户与启动服务

配置文件写好后，需要创建对应的用户并启动服务。

创建专用的系统用户：执行以下命令创建 mihomo 用户和组。--system 表示创建系统用户，--no-create-home 表示不创建 home 目录（我们用不到）。
```
sudo groupadd --system mihomo
sudo useradd --system --gid mihomo --no-create-home --shell /usr/sbin/nologin mihomo
```

设置配置目录的权限：确保 mihomo 用户能读取配置文件。

sudo chown -R root:mihomo /etc/mihomo
sudo chmod 750 /etc/mihomo

如果你的服务配置了 ReadWritePaths=/var/lib/mihomo，还需要创建该目录并授予权限：

sudo mkdir -p /var/lib/mihomo
sudo chown mihomo:mihomo /var/lib/mihomo
sudo chmod 750 /var/lib/mihomo

sudo chown mihomo:mihomo /usr/local/bin/mihomo
sudo chmod 755 /usr/local/bin/mihomo

启动服务并设置开机自启：现在，可以通知 systemd 重载配置，并启动服务了。

# 重新加载 systemd 管理器配置
sudo systemctl daemon-reload
# 设置开机自启
sudo systemctl enable mihomo
# 立即启动服务
sudo systemctl start mihomo

四、日常管理与维护

服务运行起来后，你可以通过以下命令来管理它：

查看状态：
```
sudo systemctl status mihomo
```
查看日志：
```
sudo journalctl -u mihomo -f -n 50
```
-f 表示实时跟踪，-n 50 表示显示最后50行日志。

停止/重启：

sudo systemctl stop mihomo
sudo systemctl restart mihomo

重新加载配置（发送 HUP 信号）：修改了 config.yaml 后，可以优雅地重载配置而不用中断服务。
```
sudo systemctl reload mihomo
# 或者
sudo kill -HUP $(pidof mihomo)
```

五、自动部署管理面板（可选）

mihomo 支持在启动时自动下载并部署 Web 管理面板（如 MetaCubeXD），让你可以通过浏览器直观地查看日志、切换节点、测试延迟等。只需在配置文件中添加几行配置，mihomo 就会在启动时自动完成面板的下载、解压和挂载。

1. 修改核心配置文件

编辑 /etc/mihomo/config.yaml，在适当位置（通常在 external-controller 相关配置段）添加以下三行：

external-controller: 0.0.0.0:9090      # 必须：开启外部控制 API，监听所有网卡的 9090 端口
external-ui: ui                         # 指定存放面板文件的目录名（相对路径，相对于工作目录 /etc/mihomo）
external-ui-url: "https://ghproxy.cn/github.com/MetaCubeX/metacubexd/archive/gh-pages.zip" # 面板的下载地址

配置说明：

external-controller：开启 RESTful API，mihomo 会监听此地址，供面板调用。
external-ui：面板静态文件的存放目录。此处使用相对路径 ui，即 mihomo 将在工作目录 /etc/mihomo 下创建 ui 文件夹。
external-ui-url：面板压缩包的下载链接。mihomo 启动时会自动从该地址下载并解压到 ui 目录。

2. 确保面板目录可写

由于 external-ui 指定的目录（/etc/mihomo/ui）需要由 mihomo 用户创建和写入文件，因此必须确保该用户对 /etc/mihomo 目录有写入权限。

在之前配置的 systemd 服务中，我们启用了严格的安全保护（ProtectSystem=strict），默认会将 /etc 挂载为只读。为了让 mihomo 能在 /etc/mihomo 下创建 ui 文件夹并写入面板文件，有两种解决方案：

方案 A（推荐）：修改 systemd 服务，允许写入 `/etc/mihomo`

编辑 /etc/systemd/system/mihomo.service，在 [Service] 部分的 ReadWritePaths 中添加一行：

ReadWritePaths=/etc/mihomo

修改后执行：

sudo systemctl daemon-reload

这样既保留了大部分系统目录的只读保护，又单独放行了配置目录。

方案 B（更安全）：将面板目录指向已有可写路径

如果你不希望放宽对 /etc 的保护，可以将 external-ui 设置为一个已经允许写入的绝对路径，例如 /var/lib/mihomo/ui。

external-ui: /var/lib/mihomo/ui

并确保该目录存在且属主为 mihomo：

sudo mkdir -p /var/lib/mihomo/ui
sudo chown mihomo:mihomo /var/lib/mihomo/ui
sudo chmod 750 /var/lib/mihomo/ui

注意：/var/lib/mihomo 已在之前的 systemd 配置中通过 ReadWritePaths 开放了写入权限，因此无需修改服务文件。

3. 防火墙放行 9090 端口

面板需要通过 9090 端口访问，请确保防火墙允许外部设备连接该端口。

如果使用 firewalld：

sudo firewall-cmd --permanent --add-port=9090/tcp
sudo firewall-cmd --reload

如果使用 ufw：

sudo ufw allow 9090/tcp

4. 重启服务并验证

重新加载配置并重启 mihomo 服务（reload 可能不会触发面板下载，建议直接 restart）：

sudo systemctl restart mihomo

查看日志，确认面板是否下载成功：

sudo journalctl -u mihomo -f -n 50

如果日志中出现类似以下信息，说明面板已自动部署：

... downloading ui from https://ghproxy.cn/github.com/MetaCubeX/metacubexd/archive/gh-pages.zip ...
... extracted ui to /etc/mihomo/ui

5. 访问面板

在浏览器中输入 http://<你的Linux设备IP>:9090/ui，即可打开管理面板。首次访问时，面板可能需要与 mihomo 建立连接，请确保 API 地址正确（默认为面板所在设备的 <你的Linux设备IP>:9090）。

6.故障排查

面板无法访问：检查防火墙是否放行 9090 端口；确认 external-controller 配置正确且 mihomo 正常运行。
面板未自动下载：检查 external-ui-url 是否可访问（可手动在服务器上用 curl -I 测试）；确认 mihomo 用户对目标目录有写入权限；查看日志中是否有权限错误或下载失败信息。
手动部署面板：如果自动下载失败，可以手动从 MetaCubeX/metacubexd 仓库下载 gh-pages.zip，解压到指定的 ui 目录（确保 index.html 等文件直接位于目录内），然后重启服务。

使用GitHub Actions 安全部署到阿里云 ECS

Thu, 05 Mar 2026 00:00:00 GMT

使用GitHub Actions 安全部署到阿里云 ECS

::github{repo="daitcl/Secure-Deploy-to-Aliyun-ECS"}

2026年4月21日年修复报错 'AuthorizeSecurityGroup' is not a valid api 的问题，添加了 --version 2014-05-26 --force 参数，彻底解决了全新环境下首次调用阿里云 CLI 时出现的权限校验失败问题。

1. 概述

目标：在 GitHub Actions 运行部署任务时，自动获取运行器的公网 IP，通过阿里云 API 将该 IP 临时加入安全组（仅允许访问 22 端口），部署完成后立即删除该规则，从而避免长期开放端口带来的安全风险。
优势：避免长期开放 22 端口，大幅降低被扫描和暴力破解的风险。
适用场景：需要从 GitHub Actions 安全地 SSH 登录阿里云 ECS 进行部署的任何项目。

2. 准备工作：阿里云端配置

2.1 确认 ECS 实例和安全组信息

登录阿里云控制台，进入 ECS 管理页面。
找到目标实例，记录以下信息（后续需要填入 GitHub Secrets）：
- 实例所属地域 ID（例如 cn-hangzhou，详见第 5 节表格）
- 实例绑定的安全组 ID（例如 sg-xxxxxx）
进入该安全组的 入方向规则 页面，删除所有允许 0.0.0.0/0 访问 22 端口的规则。目前可以保持为空，或仅保留内网访问规则。

2.2 创建 RAM 子账号并授权

为 GitHub Actions 创建一个专用的 RAM 子用户，并授予管理安全组的权限。

访问 RAM 控制台。
创建用户：
- 登录名称：例如 github-actions
- 访问配置：勾选 使用永久 AccessKey 访问
- AccessKey：勾选 我确认必须创建 AccessKey（系统将生成 AccessKey ID 和 Secret）
保存 AccessKey ID 和 Secret（务必立即保存，关闭后将无法再次查看）。
为该用户授权（新增授权）：
- 添加权限 AliyunECSFullAccess（系统策略，允许管理 ECS 资源，包括安全组）。
- 若需更精细的权限，可参考 8.3 节自定义策略。

3. GitHub 仓库配置 Secrets

在 GitHub 仓库的 Settings → Secrets and variables → Actions 中添加以下敏感信息：

Secret 名称	说明
`ALIYUN_ACCESS_KEY_ID`	上一步创建的 RAM 用户的 AccessKey ID
`ALIYUN_ACCESS_KEY_SECRET`	对应的 AccessKey Secret
`ALIYUN_REGION`	ECS 实例所在地域 ID（例如 `cn-hangzhou`）
`ALIYUN_SECURITY_GROUP_ID`	安全组 ID（例如 `sg-xxxxxx`）

如果你还需要通过 SSH 部署，请额外添加以下 Secrets（可选）：

REMOTE_HOST：ECS 公网 IP 或域名

REMOTE_USER：SSH 用户名

SSH_PRIVATE_KEY：SSH 私钥

4. 通用 GitHub Actions 工作流模板

将以下代码片段放入你的工作流文件中（如 .github/workflows/deploy.yml），并在 # 在这里插入你的构建/部署步骤 处替换为你自己的任务。

name: Secure Deploy to Aliyun ECS

on:
  push:
    branches: [ main ]   # 触发分支，可按需修改

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # ---------- 1. 获取当前运行器的公网 IP ----------
      - name: Get Runner Public IP
        id: ip
        run: |
          RUNNER_IP=$(curl -s http://ifconfig.me)
          echo "CURRENT_IP=$RUNNER_IP" >> $GITHUB_OUTPUT
          echo "Runner IP: $RUNNER_IP"

      # ---------- 2. 安装阿里云 CLI（二进制方式）----------
      - name: Install Aliyun CLI
        run: |
          curl -LO "https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz"
          tar -xzf aliyun-cli-linux-latest-amd64.tgz
          mkdir -p $HOME/.local/bin
          mv aliyun $HOME/.local/bin/
          echo "$HOME/.local/bin" >> $GITHUB_PATH
          aliyun --version

      # ---------- 3. 临时放行当前 IP（22 端口）----------
      - name: Authorize Security Group (Add IP)
        env:
          ALIBABA_CLOUD_ACCESS_KEY_ID: ${{ secrets.ALIYUN_ACCESS_KEY_ID }}
          ALIBABA_CLOUD_ACCESS_KEY_SECRET: ${{ secrets.ALIYUN_ACCESS_KEY_SECRET }}
          ALIBABA_CLOUD_REGION_ID: ${{ secrets.ALIYUN_REGION }}
        run: |
          aliyun ecs AuthorizeSecurityGroup \
            --RegionId ${{ secrets.ALIYUN_REGION }} \
            --SecurityGroupId ${{ secrets.ALIYUN_SECURITY_GROUP_ID }} \
            --IpProtocol tcp \
            --PortRange 22/22 \
            --SourceCidrIp ${{ steps.ip.outputs.CURRENT_IP }}/32 \
            --Policy accept \
            --NicType intranet \
            --version 2014-05-26 \
            --force

      # （可选）等待几秒让规则生效
      - name: Wait for rule to take effect
        run: sleep 5

      # ---------- 在这里插入你的构建/部署步骤 ----------
      # 例如：
      # - name: Build and Deploy
      #   run: |
      #     echo "Your deployment commands here"
      #   # 或使用 SSH Action：
      # # ---------- 验证 SSH 访问成功 ----------
      # - name: Verify SSH Connection
      #   uses: appleboy/ssh-action@v1.0.3
      #   with:
      #     host: ${{ secrets.REMOTE_HOST }}          # ECS 公网 IP 或域名
      #     username: ${{ secrets.REMOTE_USER }}      # 登录用户名（如 root 或普通用户）
      #     key: ${{ secrets.SSH_PRIVATE_KEY }}       # 私钥内容（需在 secrets 中配置）
      #     port: 22                                   # SSH 端口，默认 22
      #     script: |
      #       echo "✅ SSH connection to ECS is successful!"
      #       echo "Hostname: $(hostname)"
      #       echo "Current user: $(whoami)"
      #       echo "Working directory: $(pwd)"
      #       # 可以在此处添加更多验证命令，如检查必要目录是否存在

      # ---------- 4. 撤销放行（删除刚才添加的规则）----------
      - name: Revoke Security Group (Remove IP)
        if: always()
        env:
          ALIBABA_CLOUD_ACCESS_KEY_ID: ${{ secrets.ALIYUN_ACCESS_KEY_ID }}
          ALIBABA_CLOUD_ACCESS_KEY_SECRET: ${{ secrets.ALIYUN_ACCESS_KEY_SECRET }}
          ALIBABA_CLOUD_REGION_ID: ${{ secrets.ALIYUN_REGION }}
        run: |
          aliyun ecs RevokeSecurityGroup \
            --RegionId ${{ secrets.ALIYUN_REGION }} \
            --SecurityGroupId ${{ secrets.ALIYUN_SECURITY_GROUP_ID }} \
            --IpProtocol tcp \
            --PortRange 22/22 \
            --SourceCidrIp ${{ steps.ip.outputs.CURRENT_IP }}/32 \
            --NicType intranet \
            --version 2014-05-26 \
            --force || true

5. 阿里云地域与可用区对照表

在配置 ALIYUN_REGION 时，请根据你的 ECS 实例所在地域选择对应的地域 ID（例如 cn-hangzhou）。

地域名称	地域ID
华北1（青岛）	cn-qingdao
华北2（北京）	cn-beijing
华北3（张家口）	cn-zhangjiakou
华北5（呼和浩特）	cn-huhehaote
华北6（乌兰察布）	cn-wulanchabu
华东1（杭州）	cn-hangzhou
华东2（上海）	cn-shanghai
华东5（南京-本地地域）	cn-nanjing
华东6（福州-本地地域）	cn-fuzhou
华中1（武汉-本地地域）	cn-wuhan-lr
华南1（深圳）	cn-shenzhen
华南2（河源）	cn-heyuan
华南3（广州）	cn-guangzhou
西南1（成都）	cn-chengdu
中国香港	cn-hongkong
新加坡	ap-southeast-1
澳大利亚（悉尼）	ap-southeast-2
马来西亚（吉隆坡）	ap-southeast-3
印度尼西亚（雅加达）	ap-southeast-5
菲律宾（马尼拉）	ap-southeast-6
泰国（曼谷）	ap-southeast-7
印度（孟买）	ap-south-1
日本（东京）	ap-northeast-1
韩国（首尔）	ap-northeast-2
美国（硅谷）	us-west-1
美国（弗吉尼亚）	us-east-1
德国（法兰克福）	eu-central-1
英国（伦敦）	eu-west-1
阿联酋（迪拜）	me-east-1
沙特（利雅得-合作伙伴运营）	me-central-1

注意：安全组授权时只需要地域 ID，无需指定具体的可用区。

6. 步骤详解

步骤 1：获取运行器 IP

使用 ifconfig.me 服务获取当前 GitHub Actions 运行器的公网出口 IP。
将 IP 保存到 steps.ip.outputs.CURRENT_IP 中，供后续步骤使用。
也可使用其他服务如 ip.sb、icanhazip.com。

步骤 2：安装阿里云 CLI

直接下载官方最新版 CLI 二进制文件，解压后放入 PATH，避免依赖第三方 Action，更稳定可靠。

步骤 3：添加安全组规则

调用 AuthorizeSecurityGroup 接口，将当前 IP 添加到安全组，协议 TCP，端口 22。
--NicType intranet 适用于 VPC 网络的实例；如果是经典网络，可能需要改为 internet。
新增参数说明：--version 2014-05-26 指定 API 版本，--force 绕过本地元数据校验，两者结合可彻底解决新版 CLI 在全新环境下首次调用时出现的 'AuthorizeSecurityGroup' is not a valid api 错误。
添加规则后等待几秒，确保规则生效（可选，但推荐）。

步骤 4：插入你的构建/部署步骤

在这里执行你原本的构建、测试、SSH 部署等操作。
由于安全组已临时放行，SSH 连接可以成功。

步骤 5：删除安全组规则

调用 RevokeSecurityGroup 接口，传入与添加时完全相同的参数，精确删除规则。
if: always() 确保无论部署步骤成功或失败，都会执行清理，避免规则残留。
末尾的 || true 可防止因规则不存在（例如添加失败）而导致撤销步骤报错，从而使整个工作流标记为失败。

7. 注意事项与常见问题

Q1：授权/撤销时返回错误 `InvalidIpProtocol.Malformed` 或 `InvalidParameter`

检查 --PortRange 格式是否为 22/22，--SourceCidrIp 是否带 /32。
确保地域 ID、安全组 ID 正确，且 RAM 用户有相应权限。
确认 --NicType 与实例网络类型匹配（VPC 用 intranet，经典网络用 internet）。

Q2：阿里云 CLI 报错 `'AuthorizeSecurityGroup' is not a valid api`

此问题常见于全新安装的阿里云 CLI，原因是首次调用时未能成功下载 ECS 产品的元数据定义。
解决方法：在命令中添加 --version 2014-05-26 --force 参数（本文模板已包含），可强制跳过本地校验直接发起请求。

Q3：SSH 部署失败（连接超时或权限被拒）

可能原因：安全组规则尚未生效。可在授权后增加 sleep 5 步骤。
检查 ECS 实例内部防火墙（如 iptables）是否允许 22 端口，安全组只是网络层过滤。
确认 SSH 服务正在运行，且公钥已正确配置到 ~/.ssh/authorized_keys。

Q4：撤销步骤失败，导致规则残留

确保撤销步骤的参数与添加步骤完全一致（包括大小写、空格、掩码等）。
检查 if: always() 是否正确添加。

Q5：阿里云 CLI 提示权限不足

确认 RAM 用户已授予 AliyunECSFullAccess 权限，并且 AccessKey 正确无误。

Q6：安全组规则达到上限

每个安全组默认最多添加 200 条规则（以阿里云文档为准）。如果频繁执行且删除失败导致规则堆积，可能达到上限。建议定期检查并手动清理残留规则。

Q7：GitHub Actions IP 变更

GitHub 的 runners IP 地址范围可能变化，但每个 job 的出口 IP 是固定的。本方案动态获取当前 IP，无需预知 IP 段，因此不受影响。

8. 进阶优化

8.1 超时保护

在使用 SSH Action 时，可设置 timeout 参数（如 appleboy/ssh-action 支持 timeout），防止部署任务长时间卡住导致规则一直开放。

8.2 并发处理

多个 workflow 同时运行时，会各自添加和删除自己的 IP 规则，互不影响。但需注意安全组规则数量上限。

8.3 自定义 RAM 策略（最小权限）

若需最小权限，可创建自定义策略，仅允许操作特定安全组。示例策略如下（需将 cn-hangzhou 和 sg-xxxxxx 替换为实际值）：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:AuthorizeSecurityGroup",
        "ecs:RevokeSecurityGroup"
      ],
      "Resource": "acs:ecs:cn-hangzhou:*:securitygroup/sg-xxxxxx"
    }
  ]
}

8.4 使用 OIDC 代替长期 AccessKey（高级）

GitHub Actions 支持 OIDC 与阿里云 RAM 角色集成，可避免管理 AccessKey Secret，进一步提升安全性。具体配置请参考阿里云官方文档。

使用Github Action 定时签到科研通

Fri, 08 Aug 2025 00:00:00 GMT

科研通自动签到：GitHub Actions 每日定时签到

这是一个用于科研通（AbleSci）网站的自动签到脚本，支持青龙面板和GitHub Actions双平台运行。每日自动签到，可配置多个账号，签到结果通过多种渠道推送通知。

::github{repo="daitcl/ablesciSign"}

✨ 核心功能

🔑 自动登录科研通网站
📅 每日自动签到获取积分（默认 7:40、21:40 执行）
👥 支持多账号批量签到
📊 显示用户信息（用户名、积分、连续签到天数）
🔔 支持多平台消息通知（Server酱、息知、PushPlus等）
⚙️ 支持青龙面板和 GitHub Actions 双平台

🚀 快速上手

准备账号：科研通账号（邮箱:密码），多个账号用换行分隔。
选择部署平台：
- 青龙面板：添加仓库、配置环境变量。
- GitHub Actions：Fork 仓库、添加 Secrets、启用工作流。
配置通知（可选）：获取推送服务的密钥并添加到环境变量。
等待定时触发或手动运行测试。

详细步骤请参考下方部署指南。

📖 部署指南

🐉 1. 青龙面板部署

1.1 添加订阅

登录青龙面板，进入 订阅管理。
点击 新建订阅，填写以下信息：
- 名称：科研通签到
- 类型：公开仓库
- 链接：https://github.com/daitcl/ablesciSign.git
- 定时规则：40 7,21 * * *（对应北京时间 7:40 和 21:40）
- 白名单：ablesci.py|sendNotify.py
点击确定保存，并运行一次订阅拉取脚本。

1.2 配置环境变量

进入 环境变量 页面，点击 新建变量，添加以下变量：

变量名	必填	说明
`ABLESCI_ACCOUNTS`	✅	科研通账号列表，格式：`邮箱1:密码1`（多个账号用换行或分号分隔）
`SCKEY`	❌	Server酱 SCKEY（用于通知）
`XZKEY`	❌	息知 XZKEY（用于通知）
`PUSH_PLUS_TOKEN`	❌	PushPlus Token（用于通知）

账号格式示例：

user1@example.com:password1
user2@example.com:password2

1.3 安装 Python 依赖

在青龙面板的 依赖管理 中添加以下 Python 依赖：

requests
beautifulsoup4

🤖 2. GitHub Actions 部署

2.1 Fork 仓库

访问项目主页：daitcl/ablesciSign
点击右上角 Fork 按钮，将仓库复制到您的 GitHub 账户。

2.2 设置 Secrets

在您的仓库页面，点击 Settings → Secrets and variables → Actions。
点击 New repository secret，依次添加以下 Secrets：

Name	必填	Value
`ABLESCI_ACCOUNTS`	✅	科研通账号列表（格式同青龙面板）
`SCKEY`	❌	Server酱 SCKEY
`XZKEY`	❌	息知 XZKEY
`PUSH_PLUS_TOKEN`	❌	PushPlus Token

注意：为避免 GitHub Actions 报错，未使用的通知变量可留空或不添加，但若添加则值必须有效。

2.3 激活工作流

点击仓库上方的 Actions 选项卡。
在左侧选择 AbleSci Auto Sign 工作流。
点击 Enable workflow 启用。

工作流将按照 .github/workflows/ablesciSign.yml 中定义的 cron 定时执行（默认北京时间 7:40 和 21:40）。

▶️ 3. 手动触发测试

3.1 青龙面板手动运行

在 定时任务 列表中找到 科研通签到 任务，点击右侧的运行按钮。

3.2 GitHub Actions 手动触发

在 Actions 页面选择 AbleSci Auto Sign 工作流，点击 Run workflow → Run workflow 手动触发一次。

🔔 通知推送设置

📡 支持的推送平台

脚本支持以下推送服务，可同时配置多个（至少一个有效即可）：

Server酱（SCKEY）
息知（XZKEY）
PushPlus（PUSH_PLUS_TOKEN）

若同时配置多个，脚本会依次尝试发送，任一成功即视为通知成功。

🔑 获取推送密钥

Server酱（SCKEY）

访问 Server酱官网，使用 GitHub 登录。
进入发送消息页面，复制您的 SendKey（即 SCKEY）。
添加到环境变量 SCKEY。

息知（XZKEY）

访问息知官网，注册或微信扫码登录。
进入密钥管理页面，点击 创建密钥，填写名称后生成。
复制生成的密钥（XZKEY），添加到环境变量 XZKEY。

PushPlus（PUSH_PLUS_TOKEN）

访问 PushPlus官网，微信扫码登录。
进入一对一推送页面，复制页面中的 Token 值。
添加到环境变量 PUSH_PLUS_TOKEN。

⏰ 定时规则详解

脚本默认执行时间（基于 UTC 时间）：

23:40 UTC → 对应 次日北京时间 7:40
13:40 UTC → 对应 北京时间 21:40

如需修改执行时间：

青龙面板：修改订阅的定时规则或任务的 cron 表达式。
GitHub Actions：编辑仓库中的 .github/workflows/ablesciSign.yml 文件，修改 on.schedule.cron 字段。

❓ 常见问题解答

Q1: 为什么签到失败？

检查账号密码是否正确，注意邮箱和密码中不要包含空格。
确保网络能正常访问科研通网站。
查看运行日志，确认是否是网站改版导致脚本失效，如果是请提交 Issue。

Q2: 如何接收通知？

在对应平台的环境变量/Secrets 中配置至少一种通知服务的密钥。
脚本执行完成后会自动推送签到结果。

Q3: 可以配置多个账号吗？

是的，脚本支持多账号。只需在 ABLESCI_ACCOUNTS 中用换行分隔多个 邮箱:密码 即可。脚本会依次处理，并汇总通知。

Q4: 如何查看签到日志？

青龙面板：在任务日志中查看。
GitHub Actions：在 Actions 页面点击对应工作流运行记录，查看详细日志。

Q5: 需要安装额外的依赖吗？

青龙面板需要手动安装 requests 和 beautifulsoup4。GitHub Actions 环境已自动安装，无需额外操作。

📬 反馈与帮助

项目 Issues：如有问题或建议，欢迎在 GitHub Issues 提出。

终端使用代理加速的正确方式

Wed, 03 Apr 2024 00:00:00 GMT

终端使用代理加速的正确方式

我们在终端使用 Homebrew、git、npm、pip 等命令时，经常因为网络问题而安装失败。尤其是第一次安装 Homebrew，不少人需要花很长时间解决，心里不知吐槽了多少遍“该死的网络”。

虽然设置国内镜像确实有用，但镜像有时更新不及时，且没有普适性。今天就介绍一种通用的方法：让终端也走代理。这样无论你用什么包管理器，都能享受代理带来的加速。

本文以 Shadowsocks 为例，其他代理软件（如 Clash、V2Ray）配置思路完全一致，只需找到对应的 HTTP 代理端口即可。

一、macOS & Linux

1. 基础环境变量

终端命令行的网络请求默认不会经过代理，我们需要通过设置环境变量来告诉系统使用代理。

在终端中直接执行以下命令可以临时开启代理（仅对当前终端窗口有效）：

bash

export http_proxy=http://127.0.0.1:1080
export https_proxy=$http_proxy

注意：1080 是 HTTP 代理的默认端口，但你的实际端口可能不同。请打开 Shadowsocks 的偏好设置 → 高级，查看 HTTP 代理端口，将上述命令中的 1080 替换为你自己的端口。

2. 便捷脚本（永久生效）

每次都手动敲命令太麻烦，我们可以写两个函数，方便随时开关代理。

首先根据你使用的 Shell 决定配置文件：

执行 echo $SHELL 查看 Shell 类型
- /bin/bash → ~/.bash_profile
- /bin/zsh → ~/.zprofile

然后使用以下命令将脚本追加到对应的配置文件，并立即生效（以下以 .zprofile 为例，请按实际情况替换）：

cat >> ~/.zprofile << 'EOF'
function proxy_on() {
    export http_proxy=http://127.0.0.1:1080   # 端口按实际情况修改
    export https_proxy=$http_proxy
    echo -e "终端代理已开启。"
}

function proxy_off() {
    unset http_proxy https_proxy
    echo -e "终端代理已关闭。"
}
EOF

source ~/.zprofile

之后，你只需要在终端输入 proxy_on 即可开启代理，输入 proxy_off 关闭代理。

3. 验证代理是否生效

执行以下命令，如果返回的 IP 是你代理服务器的 IP，说明代理生效：

curl cip.cc

或者使用：

curl -I https://www.google.com

如果看到 HTTP/2 200 之类的响应，说明可以正常访问 Google。

注意：有时 Google 会返回 403，这是因为 Google 对某些代理 IP 做了限制，可以换用 cip.cc 验证 IP 归属地。

二、Windows

Windows 下的配置略有不同，主要有两种方法：通过 CMD/PowerShell 设置环境变量，或者使用图形化工具。

1. 临时设置（CMD）

在命令提示符中执行：

set http_proxy=http://127.0.0.1:1080
set https_proxy=http://127.0.0.1:1080

这种方法只对当前 CMD 窗口有效，关闭后失效。

2. 永久设置（系统环境变量）

通过 系统属性 → 高级 → 环境变量，为当前用户或系统添加两个变量：

变量名：http_proxy，值：http://127.0.0.1:1080
变量名：https_proxy，值：http://127.0.0.1:1080

设置后重新打开终端即可生效。

3. PowerShell 便捷函数

在 PowerShell 中，可以将函数添加到 $PROFILE 中，实现类似 Linux 的开关功能。

首先检查 $PROFILE 文件是否存在：

Test-Path $PROFILE

如果返回 False，则创建它：

New-Item -Path $PROFILE -ItemType File -Force

然后用记事本打开编辑：

notepad $PROFILE

添加以下内容：

function proxy_on {
    $env:http_proxy = "http://127.0.0.1:1080"
    $env:https_proxy = "http://127.0.0.1:1080"
    Write-Host "终端代理已开启。"
}

function proxy_off {
    Remove-Item Env:http_proxy -ErrorAction SilentlyContinue
    Remove-Item Env:https_proxy -ErrorAction SilentlyContinue
    Write-Host "终端代理已关闭。"
}

保存后，重启 PowerShell 或执行 . $PROFILE 使函数生效。之后就可以使用 proxy_on 和 proxy_off 了。

三、其他代理方式

除了设置环境变量，还有一些更灵活的方式可以实现终端代理。

1. 使用 Socks5 代理

某些代理软件只提供 Socks5 端口，没有开启 HTTP 代理。此时可以用工具将 Socks5 转换为 HTTP，或者直接设置 ALL_PROXY 变量（某些软件支持 Socks5）。

export all_proxy=socks5://127.0.0.1:1080   # 端口为 Socks5 端口
export http_proxy=socks5://127.0.0.1:1080
export https_proxy=socks5://127.0.0.1:1080

注意：并非所有命令行工具都支持 Socks5，例如 curl 和 wget 支持，但 git 需要额外配置。

2. 为 Git 单独设置代理

如果你只想让 Git 走代理，而其他命令不走，可以单独配置 Git：

# HTTP 代理
git config --global http.proxy http://127.0.0.1:1080
git config --global https.proxy http://127.0.0.1:1080

# Socks5 代理
git config --global http.proxy socks5://127.0.0.1:1080
git config --global https.proxy socks5://127.0.0.1:1080

# 取消代理
git config --global --unset http.proxy
git config --global --unset https.proxy

3. 使用 proxychains（Linux/macOS）

proxychains 是一个强大的工具，可以强制任意命令通过代理，无需修改环境变量。

安装：brew install proxychains-ng (macOS) 或 sudo apt install proxychains (Debian/Ubuntu)
配置：编辑 /etc/proxychains.conf，在末尾添加代理信息，如：
```
socks4 127.0.0.1 1080
```
使用：在需要代理的命令前加上 proxychains4（或 proxychains），例如：
```
proxychains4 brew install wget
```

4. 仅对当前命令临时启用代理

如果你不想全局开启代理，只想让某一条命令走代理，可以直接在命令前加上环境变量赋值：

http_proxy=http://127.0.0.1:1080 https_proxy=http://127.0.0.1:1080 curl cip.cc

这种方式只对紧跟的命令生效，不影响后续命令。

四、常见问题

1. 如何获取正确的代理端口？

Shadowsocks：在客户端设置中查看「HTTP 代理端口」，通常默认为 1080 或 1087。
Clash：在配置文件中查看 port（HTTP 代理端口）和 socks-port，或者打开 Clash 面板查看。
V2Ray：取决于客户端配置，一般也会提供 HTTP 或 Socks 端口。

2. 为什么设置代理后某些命令仍然很慢？

可能是 DNS 解析没有走代理。可以尝试设置 ALL_PROXY，或者使用支持远程 DNS 解析的工具（如 Clash 的 redir-host 模式）。对于 curl 等工具，也可以使用 --socks5 参数指定 Socks5 代理。

3. 使用 Google 验证时返回 403

Google 可能会检测代理 IP 并返回 403，这并不代表代理失效。建议使用 cip.cc 或 ip.sb 等 IP 查询网站验证。

Matlab 离线安装硬件支持包与附加功能的方法

Sat, 13 Jan 2024 00:00:00 GMT

Matlab 离线安装硬件支持包与附加功能的方法

当在线安装无法使用时,通过离线支持包安装附加功能

操作步骤

1. 下载离线包获取工具

访问 MathWorks 官方支持软件下载页面：下载地址
根据您的操作系统选择对应的版本，下载并运行 SupportSoftwareDownloader.exe（即下载工具）。

2. 运行下载工具并登录

双击 SupportSoftwareDownloader.exe，如果启动失败（如无响应或报错），可尝试以管理员身份运行，或多次重试。
成功启动后，界面会要求您登录 MathWorks 账号。输入已注册的邮箱和密码；若无账号，可点击界面上的注册链接完成注册。

3. 选择 Matlab 版本

登录后，工具会自动检测或要求您选择当前计算机上安装的 Matlab 版本（例如 R2023a、R2022b 等）。请确保选择与您实际版本一致的选项。
如果版本列表未出现，请返回上一步重新选择，直至正确进入下一步。

4. 选择需要安装的附加功能

工具会列出所有可用的硬件支持包和附加功能。勾选您需要的项（例如特定型号的硬件支持包、工具箱等）。
点击下一步继续。

5. 指定下载文件夹

选择或创建一个本地文件夹，用于存放下载的安装文件。建议选择一个易于访问的位置，例如 D:\Matlab_SupportPackages。
点击开始下载，等待下载完成。

6. 找到 Matlab 离线安装工具

打开 Matlab 的安装目录，找到 install_supportsoftware.exe 文件。常见路径为： Matlab安装根目录\bin\win64\install_supportsoftware.exe 例如：D:\Matlab\R2023a\bin\win64\install_supportsoftware.exe
如果找不到该文件，可在 Matlab 安装目录下搜索文件名 install_supportsoftware。

7. 复制下载的 `archives` 文件夹

下载完成后，进入第 5 步指定的文件夹，您会看到一个名为 archives 的子文件夹。这个文件夹包含了所有下载的安装文件。
将整个 archives 文件夹复制到第 6 步中 install_supportsoftware.exe 所在的目录（即 bin\win64 下）。

8. 运行离线安装

在 bin\win64 目录下，双击 install_supportsoftware.exe。
程序会自动识别 archives 文件夹中的内容，并弹出安装界面。勾选您需要安装的项，按提示完成安装。

9. 验证安装

启动 Matlab，在主页选项卡中点击附加功能 → 管理附加功能，查看已安装的硬件支持包列表，确认安装成功。

10. 安装其他附加功能

如需添加其他硬件支持包或功能，只需重新运行下载工具，将新的文件下载到同一文件夹（覆盖或合并原有的 archives 文件夹），然后再次执行 install_supportsoftware.exe 即可。

注意事项

确保 Matlab 版本与下载工具中选定的版本一致，否则可能导致安装失败。
离线安装过程中，请勿关闭 Matlab 或中断 install_supportsoftware.exe 的运行。
若下载工具始终无法正常启动，请检查网络设置、防火墙，或尝试从 MathWorks 官网重新下载该工具。

配置pcigo-command上传图床为兰空图床

Sat, 13 Jan 2024 00:00:00 GMT

pcigo-command设置lskypro

1. 准备工作

1.1 Curl的安装与配置

安装配置Curl 下载地址
解压

下载完成后，我解压到了这样一个目录

D:\bin\curl-8.4.0

配置环境变量

新建一个环境变量

变量名(N): CURL_HOME
变量值(V): D:\bin\curl-8.4.0

然后Path中追加这个环境变量即可

%CURL_HOME%\bin\

1.2 获取lsky的信息

使用 cURL(推荐)获取认证 token 信息

curl -X POST -F "email=admin@mail.com" -F "password=admin" https://test.lsky.com/api/v1/tokens

提示：

此命令仅适用于 V2，V1 用户只需要进入个人设置页面复制、粘贴使用即可。

打开终端输入命令

D:\>curl -X POST -F "email=admin@mail.com" -F "password=admin" https://test.lsky.com/api/v1/tokens
{"status":true,"message":"success","data":{"token":"1|CMhnYzsbHiGuX2YDNrMRYJdFRh466wDYzeuz53qv"}}

保存获取的认证token信息

Bearer 1|CMhnYzsbHiGuX2YDNrMRYJdFRh466wDYzeuz53qv

提示：

通过设置请求 header 标头来验证请求(Bearer Token),所以Bearer不可少

使用cURL(推荐)获取默认上传的相册ID

curl -H "Authorization:Bearer 1|CMhnYzsbHiGuX2YDNrMRYJdFRh466wDYzeuz53qv" -H "Accept:application/json" https://test.lsky.com/api/v1/albums

提示：

Authorization后面填刚保存的认证token信息

打开终端输入命令

D:\>curl -H "Authorization:Bearer 1|CMhnYzsbHiGuX2YDNrMRYJdFRh466wDYzeuz53qv" -H "Accept:application/json" https://test.lsky.com/api/v1/albums
{"status":true,"message":"success","data":{"current_page":1,"data":[{"id":3,"name":"\u65c5\u6e38","intro":"","image_num":0},{"id":2,"name":"\u65e5\u5e38","intro":"","image_num":0},{"id":1,"name":"\u56fe\u5e8a","intro":"","image_num":0}],"first_page_url":"http:\/\/test.lsky.com\/api\/v1\/albums?page=1","from":1,"last_page":1,"last_page_url":"http:\/\/test.lsky.com\/api\/v1\/albums?page=1","links":[{"url":null,"label":"&laquo; \u4e0a\u4e00\u9875","active":false},{"url":"http:\/\/test.lsky.com\/api\/v1\/albums?page=1","label":"1","active":true},{"url":null,"label":"\u4e0b\u4e00\u9875 &raquo;","active":false}],"next_page_url":null,"path":"http:\/\/test.lsky.com\/api\/v1\/albums","per_page":40,"prev_page_url":null,"to":3,"total":3}}

将返回的参数在网页整理之后可得

{
    "status": true,
    "message": "success",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 3,
                "name": "旅游",
                "intro": "",
                "image_num": 0
            },
            {
                "id": 2,
                "name": "日常",
                "intro": "",
                "image_num": 0
            },
            {
                "id": 1,
                "name": "图床",
                "intro": "",
                "image_num": 0
            }
        ],
        "first_page_url": "http://test.lsky.com/api/v1/albums?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://test.lsky.com/api/v1/albums?page=1",
        "links": [
            {
                "url": null,
                "label": "&laquo; 上一页",
                "active": false
            },
            {
                "url": "http://test.lsky.com/api/v1/albums?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "下一页 &raquo;",
                "active": false
            }
        ],
        "next_page_url": null,
        "path": "http://test.lsky.com/api/v1/albums",
        "per_page": 40,
        "prev_page_url": null,
        "to": 3,
        "total": 3
    }
}

提示：

返回参数 data.data.name 相册名称需要经过Unicode转中文

返回参数 data.data.id 相册自增 ID

保存获取的相册ID

图床 1
日常 2
旅游 3

2. 安装lsky图床插件

lsky图床插件

官方地址
安装方式在对应系统的PicGo程序配置文件路径下执行 npm i picgo-plugin-lankong，然后重启应用即可。

3. 修改配置文件

这一步需要找到第1.2步中下载的picgo二进制文件，不同系统文件名略有不同：

windows系统一般在C:\Users\用户名\AppData\Roaming\picgo\win64\文件夹，文件名为picgo.exe；
linux系统一般在~/.config/Typora/picgo/linux/文件夹，文件名为picgo；

接下来执行命令：

linux系统，打开终端，在home目录下执行./.config/Typora/picgo/linux/picgo install lankong；
windows系统，打开终端，可以在包含picgo.exe文件的路径下执行./picgo.exe install lankong；

下面以windows系统为例 在终端中打开你的picgo.exe路径，你可以通过picgo.exe -h来查看所有命令：

$ picgo.exe -h

Usage: picgo [options] [command]

Options:

  -v, --version                 output the version number
  -d, --debug                   debug mode
  -s, --silent                  silent mode
  -c, --config <path>           set config path
  -h, --help                    output usage information

Commands:

  install|add [options] <plugins...>   install picgo plugin
  uninstall|rm <plugins...>            uninstall picgo plugin
  update [options] <plugins...>        update picgo plugin
  set|config <module> [name]           configure config of picgo modules
  upload|u [input...]                  upload, go go go
  use [module]                         use modules of picgo
  init [options] <template> [project]  create picgo plugin's development templates
  i18n [lang]                          change picgo language
  help [command]                       display help for command

提示

其中，命令选项如果是用<>包围起来的为必须输入项，如果是用[]包围起来的则为可选输入项。有些命令支持简写，比如picgo upload可以写为picgo u。

使用use命令为picgo选择lsky图床

C:\Users\AppData\Roaming\picgo\win64>./picgo.exe use
? Use an uploader (Use arrow keys)
> lankong
  smms
  tcyun
  github
  qiniu
  imgur
  aliyun
(Move up and down to reveal more choices)

C:\Users\AppData\Roaming\picgo\win64>./picgo.exe use
? Use an uploader lankong
? Use a transformer (Use arrow keys)
> path
  base64

C:\Users\AppData\Roaming\picgo\win64>./picgo.exe use
? Use an uploader lankong
? Use a transformer path
? Use plugins (Press <space> to select, <a> to toggle all, <i> to invert selection)
>(*) picgo-plugin-lankong

C:\Users\AppData\Roaming\picgo\win64>./picgo.exe use
? Use an uploader lankong
? Use a transformer path
? Use plugins (Press <space> to select, <a> to toggle all, <i> to invert selection)picgo-plugin-lankong
[PicGo SUCCESS]: Configure config successfully!

picgo 需要配置文件来启动。当你未指定配置文件的时候，picgo 将会使用默认配置文件来启动。

自动生成

通常来说你只需要配置 Uploader 即可，所以你可以通过 picgo set uploader 来进入交互式命令行，

C:\Users\AppData\Roaming\picgo\win64>./picgo.exe set uploader
? Choose a(n) uploader (Use arrow keys)
> lankong
  smms
  tcyun
  github
  qiniu
  imgur
  aliyun
(Move up and down to reveal more choices)

C:\Users\AppData\Roaming\picgo\win64>./picgo.exe set uploader
? Choose a(n) uploader lankong
? Choose a version (Use arrow keys)
  V1
> V2

C:\Users\AppData\Roaming\picgo\win64>./picgo.exe set uploader
? Choose a(n) uploader lankong
? Choose a version V2
? 示例: https://example.com https://test.lsky.com

这里的认证 token 信息为第1.3节保存的token值

C:\Users\AppData\Roaming\picgo\win64>./picgo.exe set uploader
? Choose a(n) uploader lankong
? Choose a version V2
? 示例: https://example.com test.lsky.com
? 认证 token 信息 Bearer 1|CMhnYzsbHiGuX2YDNrMRYJdFRh466wDYzeuz53qv

这里albumId为第1.3节保存的相册ID (选择需要默认上传的这里我选择的是图床)

C:\Users\AppData\Roaming\picgo\win64>./picgo.exe set uploader
? Choose a(n) uploader lankong
? Choose a version V2
? 示例: https://example.com test.lsky.com
? 认证 token 信息 Bearer 1|CMhnYzsbHiGuX2YDNrMRYJdFRh466wDYzeuz53qv
? 选填, V1以及V2使用默认存储策略时请留空 1
? 选填, V2生效 1

C:\Users\AppData\Roaming\picgo\win64>./picgo.exe set uploader
? Choose a(n) uploader lankong
? Choose a version V2
? 示例: https://example.com test.lsky.com
? 认证 token 信息 Bearer 1|CMhnYzsbHiGuX2YDNrMRYJdFRh466wDYzeuz53qv
? 选填, V1以及V2使用默认存储策略时请留空 1
? 选填, V2生效 1
? set permission private(default)
? 是否忽略证书错误, 如果上传失败提示证书过期请设为true No
? 是否同步删除, 只支持V2 No
[PicGo SUCCESS]: Configure config successfully

默认配置文件

picgo 的默认配置文件为~/.picgo/config.json。其中~为用户目录。不同系统的用户目录不太一样。

linux 和 macOS 均为~/.picgo/config.json。

windows 则为C:\Users\你的用户名\.picgo\config.json。

可以用记事本打开

可以参考如下配置：

{
  "picBed": {
    "uploader": "lankong",
    "current": "lankong",
    "lankong": {
      "lskyProVersion": "V2",
      "server": "https://test.lsky.com",
      "token": "Bearer 1|CMhnYzsbHiGuX2YDNrMRYJdFRh466wDYzeuz53qv",
      "strategyId": "1",
      "albumId": "1",
      "permission": 0,
      "ignoreCertErr": false,
      "syncDelete": false
    },
    "transformer": "path"
  },
  "picgoPlugins": {
    "picgo-plugin-lankong": true
  }
}

基于Fuwari的文章模板简易指南

Mon, 01 Jan 2024 00:00:00 GMT

封面图片来源：Source

此博客模板基于 Astro 构建。本指南未提及的内容，可在 Astro 文档中找到答案。

文章前置参数

---
title: 我的第一篇博客文章
published: 2023-09-09
description: '这是我的新 Astro 博客的第一篇文章。
image: './cover.jpg'
tags: ['Foo', 'Bar']
category: '前端'
draft: false
lang: 'zh-CN'
pinned: false
---

属性	描述
`title`	文章标题
`published`	文章发布日期。
`description`	文章的简短描述。显示在首页。
`image`	文章的封面图片路径。<br/>1. 以 `http://` 或 `https://` 开头：使用网络图片<br/>2. 以 `/` 开头：使用 `public` 目录中的图片<br/>3. 无上述前缀：相对于 Markdown 文件的路径
`tags`	文章的标签。
`category`	文章的分类。
`draft`	如果此文仍为草稿，将不会显示。
`lang`	文章的语言。
`pinned`	文章是否置顶。

文章文件的存放位置

你的文章文件应存放在 src/content/posts/ 目录中。你也可以创建子目录，以便更好地组织文章和资源。

src/content/posts/
├── post-1.md
└── post-2/
    ├── cover.png
    └── index.md

::github{repo="saicaca/fuwari"}

兰空图床配置上传相册

Mon, 04 Dec 2023 00:00:00 GMT

兰空图床设置上传相册

需求

在使用 API 上传图片时，希望能够通过参数指定目标相册。同时，Web 上传界面也应支持此功能。

解决方法：

修改文件 /app/Services/ImageService.php 第 139 行附近，调整相册分配逻辑。

原代码（仅使用用户默认相册）：

// 图片保存至默认相册(若有)
if ($albumId = $user->configs->get(UserConfigKey::DefaultAlbum)) {
    if ($user->albums()->where('id', $albumId)->exists()) {
        $image->album_id = $albumId;
    }
}

修改后代码（优先使用请求参数中的 album_id，否则回退到默认相册）：

// 如果请求中包含 album_id，则优先使用
if ($request->has('album_id')) {
    $image->album_id = $request->input('album_id');
} else {
    // 图片保存至默认相册(若有)
    if ($albumId = $user->configs->get(UserConfigKey::DefaultAlbum)) {
        if ($user->albums()->where('id', $albumId)->exists()) {
            $image->album_id = $albumId;
        }
    }
}

使用方式

修改后，在 API 请求的 formdata 中添加 album_id 参数即可指定相册。示例（Flutter/Dart）：

formdata = FormData.fromMap({
    "file": await MultipartFile.fromFile(path, filename: name),
    "strategy_id": 1,
    "album_id": 4,      // 指定相册 ID
});

注意事项

确保传递的 album_id 存在且属于当前用户，否则可能报错。
若请求中未提供 album_id，则仍按用户默认相册设置处理。
Web 上传界面的支持需前端配合传递该参数，此修改仅服务端生效。

通过此修改，即可灵活控制图片上传到指定相册。

Dait's 技术小栈

C语言实现面向对象编程（OOP）补充内容

C语言实现面向对象编程（OOP）补充内容

一、向上转型

1.1 安全的前提：基类作为首成员

1.2 如果基类不在首成员会发生什么？

1.3 多个派生类的内存分布示例

二、向下转型：container_of

2.1 关键工具：offsetof

2.2 地址回推原理

2.3 封装成宏（container_of）

2.4 在继承模拟中使用

2.5 风险与使用原则

三、虚函数防御

3.1 核心防御手段

3.2 安全调用宏

3.3 防御检查清单

四、完整测试代码与运行结果

小结

C语言实现面向对象编程（OOP）基础教程

C语言实现面向对象编程（OOP）基础教程

一、封装成员变量

1.1 结构体定义与构造函数

1.2 要点小结

1.3 完整代码如下

二、封装成员函数

2.1 修改结构体，加入函数指针

2.2 要点小结

2.3 完整代码

三、隐藏this指针（仅供学习）

3.1 引入全局 this 指针

3.2 要点小结

3.3 缺陷一览

3.4 完整代码

四、隐藏成员变量

4.1 使用私有数据结构

4.2 要点小结

4.3 注意事项

4.4 完整代码

五、多文件与显式 this 参数（推荐）

5.1 头文件 person.h

5.2 实现文件 person.c

5.3 测试文件 test5.c

5.4 要点小结

5.5 注意事项

5.6 完整项目文件

六、继承与多态

6.1 简单继承——每个对象独立函数指针

6.1.1 要点小结

6.1.2 注意事项

6.2 虚函数表（vtable）——多态的高效实现

6.2.1 要点小结

6.2.2 注意事项

6.3 多文件

6.4 本章总结

Qt6基础教程：多线程串口通信实战

Qt6基础教程：多线程串口通信实战

一、创建串口工作类 SerialWorker

1.1 基本框架

1.2 加入串口对象成员

1.3 串口的打开与关闭

1.4 接收数据：解决粘包与界面卡顿

1.5 发送数据：支持文本与十六进制

1.6 完善错误处理与状态信号

二、创建管理类 SerialManager

2.1 定义 SerialManager 类的基本框架

2.2 添加对外公开接口

2.3 添加内部请求信号

2.4 添加转发信号

2.5 实现构造函数

2.6 实现析构函数

2.7 实现公开接口

三、创建简易Demo

3.1 搭建基础界面与 SerialManager 集成

3.2 初始化串口参数下拉框

3.3 获取可用串口列表

3.4 打开与关闭串口

3.5 实现数据发送（支持纯文本与十六进制）

3.6 实现数据接收与显示

3.7 实现定时发送

一、创建串口工作类 `SerialWorker`

二、创建管理类 `SerialManager`

2.1 定义 `SerialManager` 类的基本框架

3.1 搭建基础界面与 `SerialManager` 集成

四、回顾与总结

1.基于内置地理数据的 Mihomo 配置文件

方案 A（推荐）：修改 systemd 服务，允许写入 `/etc/mihomo`