版本：Conan 2.x | 适用对象：C/C++ 开发工程师
1. Conan 简介
Conan 是一款专为 C 和 C++ 设计的开源、去中心化包管理器，帮助开发团队高效管理第三方依赖库，支持跨平台构建与多版本并存。
1.1 为什么选择 Conan？
• 跨平台支持：Windows、Linux、macOS 全面兼容
• 支持多种构建系统：CMake、MSBuild、Autotools、Meson 等
• 版本精确控制：可对同一依赖的不同版本共存管理
• 私有仓库支持：可搭建内网 Artifactory 或 Conan Server
• 丰富的社区生态：ConanCenter 提供数千个预编译包
1.2 Conan 核心概念
概念 说明
Package 经过编译的二进制库或头文件，带有版本和平台信息
Recipe (conanfile.py) 描述包如何构建、依赖及打包的 Python 脚本
Profile 定义目标平台、编译器、ABI 等构建环境的配置文件
Remote 包的远程仓库地址（如 ConanCenter、私有 Artifactory）
Lockfile 锁定依赖版本，保证构建可复现性
2. 环境要求与前置准备
2.1 系统要求
操作系统 最低要求 推荐配置
Windows Windows 10 64-bit, Python 3.8+ Windows 11, Python 3.11+
Linux Ubuntu 20.04+, Python 3.8+ Ubuntu 22.04, Python 3.11+
macOS macOS 11+, Python 3.8+ macOS 13+, Python 3.11+
2.2 前置依赖
• Python 3.8 或更高版本（建议 3.10+）
• pip 包管理器（随 Python 安装）
• Git（用于拉取 recipe 等）
• 对应平台的 C/C++ 编译器（GCC、Clang 或 MSVC）
• CMake 3.15+（推荐）
3. Conan 安装步骤
3.1 通过 pip 安装（推荐）
在终端或命令提示符中执行以下命令：
第一步：升级 pip
python -m pip install --upgrade pip
第二步：安装 Conan
pip install conan
第三步：验证安装
conan --version
若输出类似 conan/2.x.x 的版本信息，则安装成功。
3.2 Windows 特殊说明
• 建议使用 PowerShell 或 Windows Terminal（管理员模式）
• 若环境变量未自动配置，需手动将 Python Scripts 目录加入 PATH
# PowerShell 示例，将 Scripts 目录加入当前用户 PATH
$env:PATH += ";$env:USERPROFILE\AppData\Local\Programs\Python\Python311\Scripts"
3.3 Linux / macOS 特殊说明
• 建议在 Python 虚拟环境（venv）中安装，避免污染系统环境
python3 -m venv conan-env source conan-env/bin/activate pip install conan
• macOS 用户也可使用 Homebrew：brew install conan
3.4 离线/内网安装
若公司内网无法访问外部网络，可通过以下方式离线安装：
- 在有网络的机器上下载安装包：pip download conan -d ./conan-packages
- 将 conan-packages 目录拷贝至内网机器
- 在内网机器执行：pip install --no-index --find-links=./conan-packages conan
4. 初始配置
4.1 生成默认 Profile
安装完成后，需要生成默认的构建配置文件（Profile），Conan 会自动检测本机编译器：
conan profile detect
该命令会在 ~/.conan2/profiles/default 生成配置文件，内容示例如下：
[settings] os=Linux arch=x86_64 compiler=gcc compiler.version=11 compiler.libcxx=libstdc++11 build_type=Release
4.2 配置远程仓库
默认已配置 ConanCenter（官方公共仓库），可通过以下命令查看和添加远程仓库：
# 查看远程仓库列表
conan remote list
# 添加公司内网私有仓库（示例）
conan remote add mycompany https://artifactory.mycompany.com/conan
4.3 设置认证信息
conan remote login mycompany <用户名> -p <密码>
5. 基本使用
5.1 搜索依赖包
搜索 zlib 相关包 conan search zlib --remote=conancenter
5.2 安装依赖（conanfile.txt）
在项目根目录创建 conanfile.txt：
[requires] zlib/1.2.13 openssl/3.1.0 [generators] CMakeDeps CMakeToolchain
然后执行安装：
conan install . --output-folder=build --build=missing
5.3 与 CMake 集成
cd build cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release cmake --build .
5.4 常用命令速查
命令 说明
conan install . 安装当前项目依赖
conan create . 打包当前 recipe 为 Conan 包
conan upload <pkg> -r <remote> 上传包到远程仓库
conan search <name> 在本地缓存中搜索包
conan remove <pkg> 从本地缓存删除包
conan profile list 列出所有 Profile
conan cache path <pkg> 查看包在本地缓存中的路径
conan lock create . 生成依赖锁定文件
6. 常见问题与排查
6.1 安装报错：权限不足
在 Linux/macOS 上出现 Permission denied，不要使用 sudo pip install，建议改用虚拟环境（参见 3.3 节）。
6.2 找不到包或版本不存在
先通过 conan search 确认包名和版本拼写，再通过 --remote 指定正确仓库。如果包不存在，可尝试 conan create 自行打包。
6.3 编译器版本不匹配
修改 ~/.conan2/profiles/default 中的 compiler.version 与本机实际版本保持一致，然后重新执行安装。
6.4 网络超时或代理设置
# 设置 HTTP 代理
export CONAN_HTTP_PROXY=http://proxy.mycompany.com:8080
export CONAN_HTTPS_PROXY=http://proxy.mycompany.com:8080
7. 培训总结
本文档涵盖了 Conan 2.x 的安装、配置及基本使用流程，学完本培训后，您应能够：
- 在 Windows、Linux 和 macOS 上独立安装 Conan
- 生成和调整 Profile 以匹配本机编译环境
- 配置公司内部私有仓库并完成认证
- 在 C/C++ 项目中通过 conanfile.txt 管理第三方依赖
- 将 Conan 与 CMake 集成并完成构建
如有疑问，请参阅官方文档：https://docs.conan.io 或联系内部基础设施团队。
