模块声明与导出 ​

什么是 C++20 模块 ​

C++20 模块是一种替代传统头文件 #include 机制的新特性。传统头文件的工作方式是文本替换——预处理器把头文件的内容原封不动地复制到每个包含它的源文件中,这导致编译缓慢、宏污染、符号重复定义等问题。模块从根本上改变了这个机制:模块被编译一次,生成一个二进制接口文件(BMI),其他翻译单元导入这个接口即可使用其中导出的声明。

模块和命名空间是正交的概念——模块控制可见性(哪些声明能被外部看到),命名空间控制名字的作用域(避免命名冲突)。

模块 vs 头文件 ​

方面头文件(#include)模块(import)
工作方式文本替换(复制粘贴)编译一次,导入接口
编译速度慢(重复解析)快(接口只编译一次)
宏隔离无(宏会泄漏)有(模块内的宏不泄漏)
声明顺序有影响(先声明后使用)无影响(导出的名字都可见)
符号可见性默认全部可见只有导出的才可见
ODR 违反风险高(多次包含可能重复定义)低(模块接口唯一)
构建依赖需要 include guard 或 #pragma once自动处理

模块声明语法 ​

每个模块单元(Module Unit)的开头必须有一个模块声明:

[export] module 模块名 [:分区名] ;
  • export module M; —— 声明模块接口单元(对外可见)
  • module M; —— 声明模块实现单元(内部使用)
  • 模块名由标识符和点号组成,如 math、graphics.shapes、my_lib.utils
  • 点号没有语义含义(不表示层次关系),只是命名约定

导出声明 ​

模块中的声明默认是模块内部的(不可见)。要让外部使用,需要显式导出。导出有三种形式:

直接导出 ​

cpp
// math.cppm(模块接口单元)
export module math;

// 导出函数
export int add(int a, int b) {
    return a + b;
}

// 导出类
export class Calculator {
public:
    int compute(int a, int b) const {
        return a + b;
    }
};

// 导出常量
export constexpr double pi = 3.14159265358979;

// 导出模板
export template<typename T>
T square(T x) {
    return x * x;
}

// 未导出的函数——模块外部不可见
int internal_helper(int x) {
    return x * 2;
}

导出块 ​

cpp
// geometry.cppm
export module geometry;

// 用花括号包裹,块内的所有声明都被导出
export {
    struct Point {
        double x, y;
    };

    struct Line {
        Point start, end;
    };

    double distance(const Point& a, const Point& b);

    constexpr int dimensions = 2;
}

// 导出块外的声明不导出
double distance_impl(double dx, double dy) {
    return /* ... */ 0.0;
}

导出命名空间 ​

cpp
// shapes.cppm
export module shapes;

// 导出整个命名空间——命名空间内的所有声明都被导出
export namespace shapes {
    class Circle {
    public:
        Circle(double r) : radius_(r) {}
        double area() const { return 3.14159 * radius_ * radius_; }
    private:
        double radius_;
    };

    class Rectangle {
    public:
        Rectangle(double w, double h) : width_(w), height_(h) {}
        double area() const { return width_ * height_; }
    private:
        double width_, height_;
    };

    double total_area(const Circle& c, const Rectangle& r) {
        return c.area() + r.area();
    }
}

// 同一命名空间但不在 export 块内——不导出
namespace shapes {
    // 这个函数模块外部看不到
    void internal_validate() {}
}

基本示例 ​

cpp
// ============================
// 文件:mymath.cppm(模块接口单元)
// ============================
export module mymath;  // 模块声明:声明这是模块 mymath 的接口单元

// 导出块:块内所有声明对外可见
export {
    // 导出的命名空间
    namespace mymath {
        // 基本算术函数
        int add(int a, int b) {
            return a + b;
        }

        int subtract(int a, int b) {
            return a - b;
        }

        int multiply(int a, int b) {
            return a * b;
        }

        // 安全除法,除数为零时返回默认值
        double divide(double a, double b, double default_val = 0.0) {
            if (b == 0.0) return default_val;
            return a / b;
        }

        // 导出的常量
        constexpr double pi = 3.14159265358979;
        constexpr double e  = 2.71828182845905;
    }
}

// 未导出的辅助函数——只在模块内部可用
namespace mymath {
    bool is_valid_divisor(double d) {
        return d != 0.0;
    }
}

// ============================
// 文件:main.cpp(使用模块的翻译单元)
// ============================
import mymath;  // 导入模块

#include <iostream>

int main() {
    // 使用导出的函数
    std::cout << "3 + 4 = " << mymath::add(3, 4) << std::endl;
    std::cout << "10 / 3 = " << mymath::divide(10.0, 3.0) << std::endl;
    std::cout << "pi = " << mymath::pi << std::endl;

    // mymath::is_valid_divisor(3.0);  // 编译错误:未导出,不可见

    return 0;
}

导出规则 ​

规则说明
只能导出命名空间作用域的声明不能导出局部变量或块作用域的声明
不能导出具有内部链接的实体static 函数/变量、匿名命名空间中的实体不能导出
导出的类自动导出其成员导出 class Foo 就导出了它的所有公有成员
导出的命名空间导出其中的声明export namespace N { ... } 导出 N 中的所有声明
不能重复导出同一声明一个声明只能被导出一次
导出声明必须在模块接口单元中模块实现单元中不能使用 export

不能导出的情况 ​

cpp
export module example;

// 错误:不能导出 static(内部链接)
// export static int x = 0;

// 错误:不能导出匿名命名空间中的实体
// namespace { export int y = 0; }

// 错误:不能在模块实现单元中导出
// (模块实现单元用 module example; 而不是 export module example;)

文件扩展名约定 ​

不同编译器对模块接口文件的扩展名有不同约定:

编译器推荐扩展名BMI 扩展名
MSVC.ixx.ifc
GCC.cppm 或 .cpp.gcm
Clang.cppm.pcm

这些扩展名不是标准规定的,只是各编译器的约定。

适用场景 ​

  • 新项目中替代头文件组织代码
  • 大型项目中减少编译时间
  • 库的接口定义(只导出公开 API)
  • 避免宏污染和头文件顺序问题

常见问题 ​

模块名中的点号有什么含义?

没有任何语义含义。std.core 不表示 std 是 core 的父模块。点号只是命名约定,用来表达逻辑上的层次关系,编译器不会因为名字中有点号而建立模块间的层次依赖。

模块中的宏会泄漏到导入者吗?

不会。这是模块和头文件的一个重要区别。模块内部定义的宏不会被导入者看到。如果你需要共享宏,仍然要用头文件。

export 可以用于 using 声明吗?

可以。export using SomeType = int; 是合法的。你也可以用 export using 把未导出的名字重新导出。

模块可以导出模板吗?

可以。函数模板、类模板、变量模板都可以导出。模板的定义会包含在模块接口中,导入者可以实例化模板。

注意事项 ​

  • 模块声明必须是翻译单元中的第一个声明(全局模块片段除外)
  • 同一模块的主接口单元只能有一个
  • 模块内未导出的声明对导入者不可见,但在模块内部的其他单元中可见
  • 编译顺序很重要——被导入的模块必须先编译
  • 当前构建系统(CMake 等)对模块的支持仍在改进中
  • 模块不能替代所有头文件场景(如宏、条件编译等仍需头文件)

编译器支持情况 ​

编译器最低支持版本支持程度
MSVC19.28 (VS 2019 16.8)较好
GCC11.0基本支持
Clang16.0基本支持

总结 ​

C++20 模块通过 export module 声明模块接口单元,用 export 关键字控制哪些声明对外可见。导出有三种形式:直接在声明前加 export、用 export { ... } 块导出多个声明、用 export namespace 导出整个命名空间。未导出的声明只在模块内部可见,这提供了比头文件更精细的可见性控制。模块编译一次生成二进制接口,导入者不需要重复解析源代码,编译速度因此得到提升。模块内的宏不会泄漏到导入者,避免了传统头文件的宏污染问题。