林杏仁Conan 是 C/C++ 世界里最能帮你“少拷贝源码、多写依赖声明”的包管理器。两个月前我帮一个老项目迁移依赖时，看见仓库里躺着的 zlib、paho 和 jsoncpp 源码文件夹，已经分不清哪份被本地改过、哪份是上游原版；这种状态持续下去，谁都不敢动公共库的版本。后来我把它们全部切到 Conan 管理，才真正感受到“依赖也是可以像 npm、cargo 一样被声明和解析的”。这篇内容按完整流程记录 Conan 从上手到能独立发布 package 的过程，同时把真正踩过的坑写出来。只要你写过 CMake、用过第三方 C/C++ 库，跟着做基本不会卡住。
1. 先弄清楚 Conan 到底替你解决哪件事
1.1 没有包管理器时，第三方库是怎么拖垮项目的
C/C++ 项目不像 Java、Go 那样自带中央仓库和版本锁定机制，第三方库一直是“能跑就行”的野路子。最轻量的是把源码拷进仓库，遇到老库直接改源码适配；复杂一点是写成独立子模块，编译时用变量指定目录；再难一点会有人把 .a、.lib、.dll 打包进二进制仓库。
这些做法短期能解决问题，可只要项目活过三个月，问题就会集中爆发：没人记得某个宏是给哪个版本加的补丁；用 MSVC 编译的动态库和当前项目的 runtime 不一致，链接阶段报 LNK2038；团队新同学拉完代码后，按 README 里写的“设置一下 include 目录”，一配就是半天。
我见过最典型的一次事故是：组里有人升级了 OpenSSL，但只改了编译机器上的环境变量，代码提交后构建机里还是旧路径，结果 CI 在签名验证阶段爆出诡异崩溃。这种崩溃的根因根本不在代码逻辑，而在依赖没有被“声明式管理”。
1.2 Conan 用“菜谱 + 仓库 + 解析器”替代手工搬运
Conan 把依赖管理拆成三个角色：用户项目里的 conanfile 相当于做菜清单，里面只写“我需要 fmt/10.2.1”“我需要 OpenSSL/3.1.4”；配置文件 profile 描述运行环境，比如操作系统、编译器、构建类型、架构；ConanCenter 这类包仓库是食材超市，已经有人把这些库按标准 recipe 做成规范化包。
真正值钱的是解析器这一层。Conan 拿到 conanfile 后，会计算整个依赖图：fmt 自身是否还依赖其他库、OpenSSL 和 zlib 的版本约束是否冲突、当前 profile 下能不能找到预编译二进制。如果某个配置恰好没有可用二进制，它会告诉你“需要用源码构建”，而不是让你对着网盘里的压缩包猜版本。
这套逻辑和 pip、npm 很像，但 C/C++ 的特殊之处在于二进制兼容没有银弹：同一个库在 GCC 和 MSVC 下编译结果不同，静态库里如果开了不同 fPIC 也会影响链接。Conan 用 settings 和 options 把这些属性做成标识，最终帮助你在系统里找到“匹配的一份产物”，而不是拿一份 ABI 不对的包硬编。
1.3 适合什么项目，不适合什么场景
Conan 最合适的是有明确构建系统、希望把依赖从项目源码里剥离出去的工程。无论是 Linux 下用 CMake 的服务器程序，还是 Windows 下用 MSVC 的桌面应用，都可以接入。它也能配合 CI 做二进制缓存：构建机装好 Conan 后，多次构建可以命中本地 package 缓存，不用每次重新编译。
不太适合的是“极度异构、源码全手工维护”的单文件嵌入式项目，或者第三方库没有提供构建脚本、很难抽象成 recipe 的孤例场景。遇到这种库，仍然需要先人工整理出构建方式，再考虑是否值得包一层。Conan 不是能消灭所有依赖问题的魔法，它解决的是依赖管理的规范化问题，前提是依赖本身能通过命令行或脚本完成构建。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装与初始配置：把环境调成可复现
2.1 Python 环境与安装命令
Conan 本身是 Python 实现的，所以第一步是准备好 Python 环境。Linux/macOS 上通常自带 python3；Windows 建议装官方 Python，并把 Python 和 Scripts 目录添加进 PATH，避免后面出现“conan 不是内部或外部命令”。
我这里用系统 Python 单独安装，不放到项目虚拟环境里，因为 Conan 更多是全局工具性质，频繁切换虚拟环境反而会让缓存位置变得混乱。如果你电脑里同时存在多个 Python 版本，务必用 python3 显式指定：
bash复制python3 -m pip install conan
conan --version
执行后能看到 Conan version 2.x.y 这类输出。当前 2.x 的官方命令和教程主要基于 Conan Center，如果你接触过 1.x 的老文档，会发现不少命令改名了，比如 conan search 在 2.x 里被 conan list 取代。后面示例都以 2.x 为准。
2.2 profile detect 生成了什么，为什么首次必须做
安装完成后，第一次用 Conan 前一定要执行：
bash复制conan profile detect
这个命令会扫描当前机器，把操作系统、CPU 架构、默认编译器、构建类型写入本机的默认 profile。不同机器生成的 profile 长这样：
ini复制[settings]
os=Linux
arch=x86_64
compiler=gcc
compiler.version=12
compiler.libcxx=libstdc++11
build_type=Release
如果你是 Windows 且装了 Visual Studio，生成的 profile 里会出现：
ini复制os=Windows
arch=x86_64
compiler=msvc
compiler.version=193
compiler.runtime=dynamic
build_type=Release
为什么要先有这一步？因为 Conan 解析依赖时需要知道“当前环境是什么”。C/C++ 没有跨系统二进制通用能力，一个包必须带着编译器、架构、runtime 等信息计算身份。不执行 detect，后续 install 会直接报缺少默认 profile，很多人以为是自己安装失败，其实只是少跑了这一行。
profile 默认放在 ~/.conan2/profiles/default。Windows 下是 C:\Users\用户名\.conan2\profiles\default。可以手动编辑，但如果同时存在多个项目的不同需求，我更推荐让不同项目使用不同 profile 文件，而不是改全局 default。这样 CI 和本地的行为能保持一致。
2.3 远端仓库怎么选：ConanCenter 与私有远端
Conan 安装后会默认注册官方远程仓库 ConanCenter，可以执行：
bash复制conan remote list
正常能看到 conancenter 指向 https://center.conan.io。绝大多数开源库都在里面，例如 fmt、zlib、openssl、boost 这些常用的都能直接下载。
如果公司内部有私有库，或者你发布了自己维护的 package，可以添加私有远端：
bash复制conan remote add myrepo http://internal.conan.example/artifactory/api/conan/conan-local
有一点提醒：远端仓库不是越多越好。多个远端都存有同名同版本包时，Conan 的下载策略会多一次远程查找，反而拖慢 install。建议 default 的远端只留 ConanCenter，私有远端在需要时通过 -r 指定。上传和发布是后面第 6 章的内容，先有一个可用的远程仓库概念就好。
3. 写第一份 conanfile.txt：fmt 示例背后的执行流程
3.1 三步写好 Demo 与 conanfile.txt
直接上手比空谈概念有效。我建了一个干净的演示工程，目录结构如下：
text复制.
├── CMakeLists.txt
├── conanfile.txt
└── src
└── main.cpp
先看 conanfile.txt，这是整个示例的心脏：
ini复制[requires]
fmt/10.2.1
[generators]
CMakeDeps
CMakeToolchain
含义很直白：声明需要 fmt 10.2.1；让 Conan 生成 CMake 能使用的依赖描述文件。源码文件 src/main.cpp 内容如下：
cpp复制#include <fmt/core.h>
int main() {
fmt::print("Hello from conan back! fmt version {}\n", FMT_VERSION);
return 0;
}
CMakeLists.txt 里并不需要写死 fmt 的路径，只要能找到 CMake 生成的包描述即可：
cmake复制cmake_minimum_required(VERSION 3.15)
project(conan_demo LANGUAGES CXX)
find_package(fmt CONFIG REQUIRED)
add_executable(demo src/main.cpp)
target_link_libraries(demo PRIVATE fmt::fmt)
3.2 conan install 执行期间发生了什么
在工程根目录执行：
bash复制conan install . --output-folder=build --build=missing
这时 Conan 做四件事。第一，读取 conanfile.txt 并加载默认 profile；第二，计算完整依赖图，fmt 如果还有下游依赖会被一并加入；第三，在本地缓存里查是否有匹配当前配置的包，没有则向远程下载；第四，因为加了 --build=missing，凡是远程找不到预编译包的，都会尝试用本机编译器从源码构建。
真正要关注的是最后输出的依赖信息。Conan 会在屏幕上显示每一层级包所解析到的版本和 revision，例如：
text复制fmt/10.2.1
如果 fmt 依赖了其他库，比如 format 实现里可能需要某些底层库，这里就会出现多级缩进。看到这些信息时，你已经拥有了一张完整的依赖树，之前手动拷贝源码时根本没法这么清晰地看到“项目实际引入了什么”。
3.3 手动调用 CMake 而不是依赖 IDE 魔法
conan install 后，build 目录下会产生大量文件，其中最重要的是 conan_toolchain.cmake 和 CMakeDeps 生成的各依赖描述文件。下一步用 CMake 配置项目：
bash复制cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake
cmake --build build
如果一切正常，执行生成的可执行文件：
bash复制./build/demo
输出 Hello from conan back! fmt version ...，你的第一个 Conan 依赖就落地了。这里我建议不要把 toolchain 路径藏在 CMakeLists 里，而是通过命令行传入。这样能清楚区分：代码本身不关心 Conan 是否存在，构建系统负责把依赖传递进来。很多新手喜欢在 CMakeLists 里写死 include(conan_toolchain.cmake)，短时间能用，但换目录换构建方式后会非常脆弱。
4. 依赖图与二进制指纹：profile 和 options 在选什么
4.1 四个概念在同一张桌上：settings/options/requires/generators
到了这一步，很多人会有一个感觉：跟着例子能跑，但把 conanfile.txt 改复杂一点就不知道规则是什么。所以有必要把 Conan 四个核心概念放在一起区分清楚。
settings 描述“外部环境条件”。操作系统种类、CPU 架构、编译器类型、编译版本、构建类型，都属于这个问题。这些不是某个库自己能决定的值，而是机器环境天然具备的属性。两份 conan install 只要 settings 不同，即使 require 同一个版本，也会算成不同的二进制组合。
options 描述“包内部的可调旋钮”。例如某个库是否编译成动态库、是否启用 OpenSSL、是否支持某些可选算法。同一个包在同一台机器上，option 开和关也会产生两个不同的二进制产物。options 通常由 recipe 作者预设默认值，用户可以在 conanfile 或命令行覆盖。
requires 描述“包的引用关系”。它只告诉你依赖哪个包、哪个版本，实际可用的二进制仍然需要结合 settings 和 options 来定位。tool_requires 是另一种特殊引用，用于构建期需要的工具，比如 cmake 本身、编译器包装器，它们不进入链接产物，这点容易混。
generators 描述“把解析结果转换成什么格式给构建系统”。用 CMake 就选 CMakeDeps，配合 CMakeToolchain；用其他构建系统就选对应的 Generator。它们只是翻译器，本身不参与依赖挑选，很多刚上手的朋友误以为加多个生成器会安装多份包，其实生成器只是生成不同格式的消费文件。
4.2 一个包的“身份”由哪些信息决定
Conan 内部并不直接用 fmt/10.2.1 作为本地缓存的目录名，而是计算出一个类似指纹的 package_id。这个指纹的输入包括：host profile 的关键 settings、recipe 中声明的 options 默认值以及命令行覆盖值、依赖图结构、上游 recipe revision。
所以在实际项目中，你经常能在输出里看到类似这样的行：
text复制fmt/10.2.1: Created package 2ab83s...
一旦某台机器上已经存在这个 package_id，Conan 会直接复用本地缓存，不会重新下载。如果本地没有匹配的 package_id，则按规则下载或构建。这也解释了为什么你切换 CMake 构建类型后，第一次 conan install 总是较慢，而第二次快很多：因为 Debug 和 Release 默认会计算为不同的 package_id，两者不会互相污染。
build_type 就属于 settings，所以把同一份源码跑出 Debug 和 Release 两个配置，Conan 会为它们分别保留一次二进制产物。这种设计避免了“依赖库是 Release，主程序是 Debug，链接时踩坑”的尴尬。
4.3 依赖冲突：升级版本为什么牵一发动全身
C/C++ 的依赖冲突通常不如 Python 那么温和，因为二进制级的 ABI 不兼容会更隐蔽。Conan 的解析器在生成依赖图时会检查版本约束，如果两个包对 fmt 的版本要求冲突，它会直接报错，展示冲突来源，而不是让链接期炸掉。
例如包 A 要求 fmt/[>=9,<10]，包 B 要求 fmt/10.2.1，Conan 会立刻告诉你这两个约束无法同时满足。你首先要做的是查看该约束定义在哪个 recipe，再决定往上升还是往下调。
另一个常见情况是传递依赖：你直接依赖 zlib 1.2.13，另一个库也依赖 zlib 但版本是 1.2.11，Conan 可能根据下游 recipe 的声明自动升级。并非每次升级都安全，所以正式项目建议把 lockfile 或确定版本约束写清楚。Conan 1.x 时期大家普遍用版本区间