Header-only库将所有代码置于头文件中，无需编译链接，使用时直接包含即可。其核心是将函数、类、模板等完整定义在头文件内，通过inline避免ODR冲突，用#pragma once或宏守卫防止重复包含，适用于模板库与轻量工具库，如fmt、Eigen。优点为易集成、无链接步骤，缺点可能增加编译时间且无法隐藏实现。示例包括内联函数、类方法及模板特化均在头文件中定义，配合命名空间封装和清晰注释提升可用性。（149字符）

编写一个 header-only 的 C++ 库，核心思路是将所有代码（包括函数定义、类实现、模板等）都放在头文件中，不生成独立的编译目标（如 .o 或 .lib）。这种设计特别适合模板库或轻量级工具库，使用时只需包含头文件即可，无需链接步骤。

什么是 Header-only 库

Header-only 库指的是整个库的功能都实现在头文件（.h 或 .hpp）中，用户使用时只需要 #include 对应文件，不需要额外编译或链接静态/动态库。这类库常见于现代 C++ 开源项目，比如 fmt、json for modern C++ 和 Eigen。

优点：

• 使用简单：只需头文件，无编译依赖
• 便于集成：可直接放入项目目录
• 模板友好：模板定义必须在头文件中可见

缺点：

立即学习“C++免费学习笔记（深入）”；

• 编译时间可能增加（重复包含）
• 无法隐藏实现细节

如何编写一个 Header-only 库

要创建一个真正的 header-only 库，需遵循以下原则和结构。

1. 将所有实现写入头文件

普通函数、类方法、模板等都要在头文件中提供完整定义，不能分离成 .cpp 文件。

例如：

// math_utils.hpp
#ifndef MATH_UTILS_HPP
#define MATH_UTILS_HPP
namespace mylib {
inline int add(int a, int b) {
return a + b;
}
class Calculator {
public:
int multiply(int x, int y);
};
// 类内定义，隐式 inline
inline int Calculator::multiply(int x, int y) {
return x * y;
}
// 模板必须在头文件中定义
template 
T max(T a, T b) {
return a > b ? a : b;
}
} // namespace mylib
endif // MATH_UTILS_HPP

2. 使用 inline 避免 ODR 冲突

Fireflies.ai

自动化会议记录和笔记工具，可以帮助你的团队记录、转录、搜索和分析语音对话。

下载

从 C++17 起，inline 关键字可用于变量和函数，确保即使在多个翻译单元中定义也不会违反“单一定义规则”（One Definition Rule）。

对于非模板的自由函数，建议加上 inline：

inline double square(double x) {
    return x * x;
}

3. 正确处理模板和特化

模板函数和类必须完整定义在头文件中。如果需要特化，也应在头文件中完成，并注意避免重复定义。

template<>
inline std::string max(std::string a, std::string b) {
    return a > b ? a : b;
}

4. 使用 include guard 或 #pragma once

防止头文件被多次包含，推荐使用：

#pragma once

或传统的宏守卫：

#ifndef MYLIB_MATH_UTILS_HPP
#define MYLIB_MATH_UTILS_HPP
...

最佳实践与注意事项

为了提升可用性和健壮性，注意以下几点：

• 命名空间封装：避免符号污染，用合理命名空间包裹所有内容
• 文档清晰：在头文件中添加注释说明用法
• 避免复杂全局对象：构造函数有副作用的全局变量可能导致未定义行为
• 尽量减少依赖：依赖越少，越容易被集成
• 支持 C++ 标准一致性：明确声明支持的 C++ 版本（如 C++17）

示例：一个完整的 header-only 日志宏

简单实用的例子：

// log.hpp
#pragma once
#include 
define LOG(msg) do { \
std::cout << "[LOG] " << msg << std::endl; \
} while(0)

用户只需 #include "log.hpp" 即可使用 LOG() 宏，无需任何链接。
基本上就这些。header-only 库的设计重点在于简洁、可移植和易于使用。只要把实现放进头文件、注意 inline 和 ODR，就能轻松构建一个现代 C++ 的 header-only 组件。不复杂但容易忽略细节。