1. 为什么要把 TensorFlow 编译成静态库
把 TensorFlow 编译成静态库这件事，听起来像是“重复造轮子”，毕竟官方已经提供了 pip 包、Docker 镜像、甚至预编译的 C++ 动态库。但真正在工业部署、嵌入式设备、或者需要把模型推理能力塞进一个独立可执行文件的场景里待过的人都知道，动态库那套依赖管理在交付环节有多折磨人。静态库的核心价值就一个：把运行时依赖全部收进最终产物里，让部署包变成一个“拷贝即用”的单文件，不用再操心目标机器上有没有装对版本的 CUDA、cuDNN、或者某个特定版本的 C++ 运行时。
我最初接触这个需求，是因为一个边缘计算盒子上的推理服务。那个盒子跑的是裁剪过的 Linux 系统，glibc 版本比开发机低了好几个小版本，动态链接的 TensorFlow 库一放上去就报GLIBC_2.29 not found。当时试过在目标机器上编译、试过用 patchelf 改 rpath、也试过把依赖库全部打包进一个目录再用启动脚本设LD_LIBRARY_PATH，每一种方案都有各自的坑。最后走通的路子，就是把 TensorFlow 的 C++ 接口编译成静态库，然后和业务代码一起链接成一个不依赖外部.so的可执行文件。这个过程踩的坑足够多，值得完整记录下来。
需要提前说明的是，TensorFlow 的静态库编译并不是官方主推的路径。官方文档里关于 C++ 静态链接的说明非常零散，Bazel 构建系统对静态库的支持也藏得很深。所以这篇文章不会给你一个“一键脚本”，而是把整个链路拆开，讲清楚每一步在做什么、为什么这么做、以及哪些地方最容易翻车。适合的读者是：需要在受限环境部署 TensorFlow 推理服务的 C++ 开发者、想把模型推理能力嵌入到桌面应用里的工程师、以及任何对 Bazel 构建大型 C++ 项目感兴趣的人。如果你只是想在服务器上跑 Python 训练脚本，那 pip 安装的版本完全够用，没必要折腾静态库。
2. 编译前的环境准备与版本决策
2.1 版本选择：为什么我不建议追最新版
TensorFlow 的版本迭代速度很快，但静态库编译的稳定性在不同版本之间差异巨大。我实测下来，2.10 到 2.13 这几个版本对静态库的支持相对成熟，Bazel 构建规则里关于cc_library的linkstatic属性处理得比较干净。再往后的版本，官方把更多精力放在了 Keras 3 和 JAX 生态上，C++ 静态库这条路径的维护力度明显下降，有些版本甚至会出现libtensorflow_cc.a缺失符号的问题。
选版本的时候还要考虑 CUDA 版本匹配。如果你需要 GPU 推理，TensorFlow 每个版本对 CUDA 和 cuDNN 的要求是锁死的。比如 TensorFlow 2.12 要求 CUDA 11.8 和 cuDNN 8.6，2.13 要求 CUDA 11.8 和 cuDNN 8.7。版本对不上，编译能过，但运行时会报CUDA driver version is insufficient之类的错误。我的建议是：先确定目标部署环境的 CUDA 驱动版本，然后倒推 TensorFlow 版本，而不是反过来。
还有一个容易被忽略的点是 Python 版本。虽然我们最终要的是 C++ 静态库，但 Bazel 构建过程中会调用 Python 脚本来生成一些头文件和配置。TensorFlow 2.10 到 2.13 官方支持 Python 3.8 到 3.11，如果你系统默认的 Python 是 3.12，构建脚本会在某个环节报ModuleNotFoundError。所以最好用 conda 或者 pyenv 建一个干净的 Python 3.10 环境专门用于编译。
2.2 工具链安装：Bazel 版本是最大的坑
TensorFlow 对 Bazel 版本的要求极其严格，每个 TensorFlow 版本都对应一个特定的 Bazel 版本范围。比如 TensorFlow 2.12 要求 Bazel 5.3.0，2.13 要求 Bazel 6.1.0。用错版本的话，构建会在加载 WORKSPACE 文件时就失败，报一堆no such attribute或者repository rule相关的错误。
安装 Bazel 我推荐用 Bazelisk，它是一个 Bazel 版本管理器，可以根据项目里的.bazelversion文件自动切换版本。TensorFlow 源码根目录下就有这个文件，所以装了 Bazelisk 之后，进入源码目录执行bazel命令时会自动下载并使用正确的版本。这比手动下载安装包省心得多。
除了 Bazel，还需要装一些系统依赖。在 Ubuntu 上，下面这些包是必须的：
sudo apt-get install build-essential git curl zip unzip python3-dev sudo apt-get install openjdk-11-jdk # Bazel 需要 JDKJDK 版本也有讲究，Bazel 5.x 和 6.x 推荐 JDK 11，用 JDK 17 可能会遇到--release参数不兼容的问题。如果你机器上已经有其他 JDK 版本，可以用update-alternatives切换，或者设置JAVA_HOME环境变量指向 JDK 11 的安装路径。
2.3 源码获取与目录结构认知
TensorFlow 源码仓库很大，完整克隆下来大概有 2GB 左右。如果网络条件一般，可以用--depth=1只拉取最新的一次提交：
git clone --depth=1 --branch=v2.13.0 https://github.com/tensorflow/tensorflow.git cd tensorflow进入源码目录后，有几个关键路径需要提前了解。tensorflow/core下面是核心运行时，tensorflow/cc是 C++ 接口层，tensorflow/lite是轻量级推理引擎。我们编译静态库主要关注的是tensorflow/cc和它依赖的tensorflow/core。另外third_party目录下是各种第三方依赖的构建规则，编译过程中 Bazel 会从这里下载大量外部仓库，所以第一次编译需要稳定的网络连接。
注意：源码目录的路径中不要包含中文或空格，Bazel 对路径的处理在某些版本下对非 ASCII 字符支持不好，会导致构建脚本找不到文件。
3. 用 Bazel 构建静态库的完整链路
3.1 配置构建选项：.tf_configure.bazelrc 的生成
TensorFlow 源码根目录下有一个configure.py脚本，运行它会交互式地询问一系列配置问题，然后生成.tf_configure.bazelrc文件。这个文件决定了编译时的关键参数，比如是否启用 CUDA、CUDA 计算能力列表、优化级别等。
运行配置脚本：
python3 configure.py脚本会依次询问：
- CUDA 支持：如果不需要 GPU，选
N，这样编译出来的静态库体积会小很多，也不依赖 CUDA 运行时。 - CUDA 计算能力：如果启用 CUDA，需要指定目标 GPU 的计算能力，比如
7.5对应 Turing 架构，8.6对应 Ampere 架构。可以填多个用逗号分隔，但每多一个都会增加编译时间。 - 优化标志：默认是
-march=native，如果编译机和部署机 CPU 架构不同，这里要改成具体的架构代号，比如-mavx2或者-msse4.2。 - 是否使用 clang：如果系统默认 gcc 版本太老，可以选 clang，但需要提前装好 clang 和 lld。
配置完成后，检查.tf_configure.bazelrc文件内容，确认关键参数符合预期。这个文件里还可以手动添加一些 Bazel 构建标志，比如--config=monolithic用于构建单体库，--define=framework_shared_object=false用于禁用共享对象。
3.2 构建目标的选择：libtensorflow_cc 还是 libtensorflow_framework
TensorFlow 的 Bazel 构建系统里，和静态库相关的目标主要有两个：
| 构建目标 | 产物 | 用途 |
|---|---|---|
//tensorflow:libtensorflow_cc.so | 动态库 | C++ 接口的共享库 |
//tensorflow:libtensorflow_framework.so | 动态库 | 框架层共享库 |
//tensorflow:libtensorflow_cc.a | 静态库 | C++ 接口的静态库 |
//tensorflow:libtensorflow_framework.a | 静态库 | 框架层静态库 |
如果直接构建//tensorflow:libtensorflow_cc.a，得到的静态库其实还依赖libtensorflow_framework里的符号。所以更稳妥的做法是构建一个“单体”静态库，把所有依赖都打进去。这需要用到--config=monolithic标志：
bazel build --config=monolithic --config=opt //tensorflow:libtensorflow_cc.a--config=opt表示开启优化，编译出来的库性能更好，但编译时间会显著增加。如果只是做功能验证，可以先用--config=fastbuild快速跑通流程，确认没问题后再用opt重新编译。
构建过程中 Bazel 会下载大量外部依赖，包括 Eigen、protobuf、absl、llvm 等。这些下载源有些在境外，网络不稳定的话很容易中断。可以配置 Bazel 的镜像源，在.bazelrc里添加：
build --experimental_repository_cache_home=/path/to/cache这样下载过的依赖会缓存到本地，下次编译不用重新下载。
3.3 编译过程中的资源消耗与时间预估
TensorFlow 的完整编译对机器资源要求很高。我实测的数据是：16 核 CPU、32GB 内存的机器上，开启 CUDA 支持编译libtensorflow_cc.a，大约需要 1.5 到 2 小时。如果关闭 CUDA，时间可以缩短到 40 分钟到 1 小时。内存方面，链接阶段峰值可能超过 16GB，如果内存不足，链接器会被 OOM killer 杀掉，报signal 9错误。
为了控制资源消耗，可以限制 Bazel 的并行任务数：
bazel build --config=monolithic --config=opt --jobs=8 //tensorflow:libtensorflow_cc.a--jobs=8表示最多同时跑 8 个编译任务。这个数字不要超过 CPU 物理核心数，否则会因为频繁上下文切换导致整体效率下降。另外可以设置--local_ram_resources=16384来限制单个任务的内存使用，避免某个编译单元吃掉太多内存。
编译过程中如果中断了，重新执行同样的命令即可，Bazel 会利用缓存跳过已经编译好的部分。但如果修改了.tf_configure.bazelrc里的关键参数，比如 CUDA 计算能力，Bazel 会认为缓存失效，需要重新编译大部分内容。
4. 静态库集成到业务代码的实操细节
4.1 头文件路径与符号可见性处理
编译完成后，静态库文件位于bazel-bin/tensorflow/libtensorflow_cc.a，头文件则分散在源码目录的各个子目录中。业务代码要使用 TensorFlow C++ 接口，需要包含的头文件主要有：
tensorflow/cc/ops/standard_ops.htensorflow/cc/client/client_session.htensorflow/core/framework/tensor.htensorflow/core/public/session.h
这些头文件又依赖大量其他头文件，手动一个个指定-I路径非常繁琐。一个实用的做法是，在编译 TensorFlow 静态库的同时，让 Bazel 生成一个头文件打包目标：
bazel build --config=monolithic --config=opt //tensorflow:install_headers这个目标会把所有对外暴露的头文件收集到bazel-bin/tensorflow/include目录下，保持和源码一致的目录结构。业务代码只需要加一个-I指向这个目录即可。
链接静态库时，符号可见性是一个容易踩的坑。TensorFlow 默认编译时会把很多符号标记为 hidden，如果业务代码需要调用这些符号，链接阶段会报undefined reference。解决办法是在编译 TensorFlow 时加上--define=framework_shared_object=false和--copt=-fvisibility=default，让所有符号都可见。但这会增大最终产物的体积，所以只在确实需要的时候才这么做。
4.2 链接顺序与依赖库的完整列表
静态库链接对顺序敏感。libtensorflow_cc.a依赖libtensorflow_framework.a，而后者又依赖 protobuf、absl、Eigen 等第三方库。正确的链接顺序是：业务目标文件 →libtensorflow_cc.a→libtensorflow_framework.a→ 第三方静态库。
第三方静态库的列表可以从 Bazel 的构建日志里提取。执行构建时加上--subcommands参数，Bazel 会打印出每个编译和链接命令的完整参数，从中可以找到所有依赖的.a文件路径。把这些路径整理成一个链接脚本，业务代码的构建系统直接引用即可。
一个典型的链接命令看起来是这样的：
g++ -o my_inference_app main.o \ -Wl,--start-group \ bazel-bin/tensorflow/libtensorflow_cc.a \ bazel-bin/tensorflow/libtensorflow_framework.a \ bazel-bin/external/com_google_protobuf/libprotobuf.a \ bazel-bin/external/com_google_absl/absl/strings/libstrings.a \ ... \ -Wl,--end-group \ -lpthread -ldl -lrt -lm--start-group和--end-group告诉链接器在这组库中循环查找符号，解决静态库之间的循环依赖问题。这个技巧在处理 TensorFlow 这种依赖关系复杂的库时非常有用。
4.3 运行时资源文件的处理
TensorFlow 静态库在运行时可能需要一些资源文件，比如 op 注册表、内核实现等。在动态库模式下，这些资源通常通过TF_LoadLibrary或者环境变量指定路径加载。静态链接后，这些资源需要以其他方式嵌入。
一个常见的做法是把 op 注册信息编译进静态库。TensorFlow 提供了tensorflow/core/framework/op_kernel.h里的注册宏，在业务代码里显式引用需要的 op，链接器就会把对应的实现拉进来。但这种方式需要手动列出所有用到的 op，容易遗漏。
更省事的做法是使用--whole-archive链接选项，强制把静态库里的所有目标文件都链接进来：
g++ -o my_inference_app main.o \ -Wl,--whole-archive \ bazel-bin/tensorflow/libtensorflow_cc.a \ bazel-bin/tensorflow/libtensorflow_framework.a \ -Wl,--no-whole-archive \ ...这样所有 op 实现都会被包含进来，不用担心遗漏。代价是最终可执行文件体积会大很多，我实测一个简单的图像分类程序，用--whole-archive链接后体积从 80MB 涨到了 300MB 左右。如果对体积敏感，可以先用--whole-archive跑通，然后用-Wl,--gc-sections配合-ffunction-sections -fdata-sections编译业务代码，让链接器自动剔除未使用的代码段。
5. 踩坑实录与排查思路
5.1 编译阶段：Bazel 报错 “no such package” 的排查
第一次编译时遇到最多的问题就是 Bazel 找不到某个外部包。错误信息通常是：
ERROR: /path/to/tensorflow/...: no such package '@com_google_absl//absl/strings':这种错误的原因通常是外部依赖没有下载成功。Bazel 会把下载的依赖放在~/.cache/bazel目录下，如果下载中断，缓存里可能只有部分文件。解决办法是删除对应的缓存目录，然后重新构建：
bazel clean --expunge--expunge会清空整个 Bazel 缓存，包括所有下载的依赖和编译产物。下次构建会重新下载所有东西，所以只在确实需要的时候用。如果只是某个特定依赖有问题，可以手动删除~/.cache/bazel/_bazel_$USER/.../external/下对应的目录。
还有一种情况是网络能通但下载速度极慢，导致 Bazel 超时。可以在.bazelrc里增加超时时间：
build --repository_cache_timeout=600或者配置代理，但这里不展开讲代理配置，因为不同环境的代理设置差异太大，而且涉及网络策略，不适合在公开文章里讨论。
5.2 链接阶段：undefined reference 的定位方法
链接阶段最常见的错误是undefined reference to 'xxx'。这个符号可能来自 TensorFlow 本身，也可能来自第三方库。定位方法是先用nm命令检查静态库里有没有这个符号：
nm -C bazel-bin/tensorflow/libtensorflow_cc.a | grep "xxx"-C参数会把 C++ 修饰名还原成可读的函数签名。如果符号在静态库里存在，但链接时还是报 undefined，那通常是链接顺序问题，需要调整库的顺序或者用--start-group包裹。
如果符号在静态库里根本不存在，那可能是编译时没有包含对应的源文件。比如某些 op 的实现默认不编译进静态库，需要显式启用。这时候要检查.tf_configure.bazelrc里有没有禁用相关特性，或者 Bazel 构建目标有没有包含对应的cc_library。
还有一种隐蔽的情况是符号被标记为 hidden。用nm查看时符号类型是t（小写）而不是T（大写），表示它是局部符号，链接器看不到。这种情况需要在编译 TensorFlow 时加-fvisibility=default重新编译。
5.3 运行阶段：静态库程序的常见崩溃原因
静态链接的程序跑起来崩溃，排查起来比动态链接更麻烦，因为没有ldd可以看依赖关系。常见的崩溃原因有几种：
第一种是 op 未注册。程序启动时 TensorFlow 会初始化 op 注册表，如果某个 op 的实现没有被链接进来，运行到对应节点时会报Op type not registered。解决办法是用--whole-archive链接，或者手动在代码里引用对应的 op 注册宏。
第二种是 protobuf 版本冲突。TensorFlow 依赖特定版本的 protobuf，如果业务代码也依赖 protobuf 且版本不同，链接时可能把两个版本的符号混在一起，运行时出现奇怪的序列化错误。解决办法是让业务代码使用和 TensorFlow 相同版本的 protobuf，或者把 protobuf 相关的符号全部隐藏起来。
第三种是线程局部存储（TLS）问题。TensorFlow 内部大量使用thread_local变量，在某些老版本 glibc 上，静态链接的 TLS 模型可能不兼容，导致程序启动时直接 segfault。这种情况需要加链接选项-Wl,-z,now和-Wl,-z,relro，强制使用更保守的 TLS 模型。
6. 体积优化与裁剪策略
6.1 用 gc-sections 剔除未使用代码
静态链接最大的副作用就是体积膨胀。一个完整的 TensorFlow 静态库加上业务代码，轻松超过 500MB。如果部署环境对体积有要求，就需要做裁剪。
最基础的裁剪手段是编译时加-ffunction-sections -fdata-sections，链接时加-Wl,--gc-sections。这两个选项让编译器和链接器以函数和数据段为单位进行垃圾回收，只保留被引用到的部分。我实测在一个只做图像分类的程序上，这个组合能把体积从 300MB 降到 120MB 左右。
但--gc-sections对 TensorFlow 的效果有限，因为 TensorFlow 内部大量使用静态注册机制，很多 op 实现通过全局构造函数注册，链接器无法判断它们是否被使用，只能全部保留。要突破这个限制，需要更激进的裁剪策略。
6.2 选择性编译：只构建需要的 op
TensorFlow 的 Bazel 构建系统支持通过--define参数控制哪些 op 被编译进来。比如：
bazel build --config=monolithic --config=opt \ --define=no_tensorflow_py_deps=true \ --define=with_select_tf_ops=true \ //tensorflow:libtensorflow_cc.awith_select_tf_ops=true会启用选择性 op 编译，只包含一组核心 op。但具体包含哪些 op 需要看 TensorFlow 源码里的tensorflow/core/kernels/BUILD文件定义。这个路径比较绕，而且不同版本的行为不一致，需要花时间研究。
另一个思路是直接用 TensorFlow Lite 代替完整的 TensorFlow。TFLite 本身就是为移动端和嵌入式设计的，静态库体积可以控制在 10MB 以内。但 TFLite 只支持推理，不支持训练，而且 op 集合比完整版少很多。如果你的场景只是跑一个固定的推理模型，TFLite 是更合适的选择。
6.3 用 strip 去除调试符号
编译时如果用了--config=opt，默认会带一些调试符号。链接完成后可以用strip命令去除：
strip --strip-all my_inference_app这个操作通常能减少 30% 到 50% 的体积。但注意--strip-all会去掉所有符号，包括动态符号表，如果程序用了dlopen或者需要打印函数名做日志，就不能用这个选项。可以用--strip-debug只去掉调试信息，保留符号表。
还有一个技巧是编译时加-g0明确不生成调试信息，从源头减少体积。TensorFlow 的默认编译选项里-g是开着的，可以在.tf_configure.bazelrc里覆盖：
build --copt=-g0但这样如果程序崩溃，堆栈信息里只有地址没有函数名，排查问题会困难一些。所以建议在开发阶段保留调试信息，发布阶段再去掉。
7. 跨平台交叉编译的注意事项
7.1 目标架构与工具链配置
交叉编译 TensorFlow 静态库到不同架构（比如从 x86_64 编译到 aarch64）是一个更复杂的场景。Bazel 支持通过--crosstool_top和--cpu参数指定交叉编译工具链，但 TensorFlow 的构建脚本对这些参数的支持并不完善。
基本步骤是：先安装目标架构的交叉编译工具链，比如gcc-aarch64-linux-gnu，然后在.tf_configure.bazelrc里指定：
build --crosstool_top=@local_config_cc//:toolchain build --cpu=aarch64 build --copt=--sysroot=/path/to/sysroot但 TensorFlow 的第三方依赖（如 protobuf、absl）也需要用交叉编译工具链重新编译，这要求这些依赖的 Bazel 构建规则支持交叉编译。实际测试中，protobuf 和 absl 的交叉编译比较顺利，但 Eigen 和 llvm 的交叉编译经常出问题，需要手动打补丁。
7.2 目标系统 glibc 版本兼容性
交叉编译时最容易忽略的是 glibc 版本兼容性。如果编译工具链使用的 sysroot 里 glibc 版本比目标系统高，链接出来的程序在目标系统上会报GLIBC_2.xx not found。解决办法是使用目标系统对应的 sysroot，或者用-Wl,--wrap之类的技巧绕过版本检查。
更稳妥的做法是在目标系统上直接编译，或者用 Docker 模拟目标系统的用户空间。比如目标系统是 Ubuntu 18.04，就在 Ubuntu 18.04 的 Docker 容器里编译，这样编译环境和运行环境的 glibc 版本一致，不会出现兼容性问题。
7.3 交叉编译产物的验证方法
交叉编译出来的静态库不能直接在开发机上运行验证，需要用qemu-user模拟目标架构来跑测试程序：
qemu-aarch64 -L /path/to/aarch64/sysroot ./my_inference_app-L参数指定目标系统的库路径，qemu 会从这个路径加载动态链接器。如果程序是纯静态链接的，理论上不需要-L，但 TensorFlow 静态库可能仍然依赖一些系统库，所以指定 sysroot 更保险。
验证时重点检查几个方面：程序能否正常启动、模型能否加载、推理结果是否和 x86_64 版本一致。如果推理结果有偏差，可能是浮点运算的架构差异导致的，需要检查编译时有没有开启-ffast-math之类的激进优化选项。
8. 一些个人经验与后续扩展思路
整个静态库编译链路走下来，我最大的体会是：TensorFlow 的构建系统虽然强大，但它的设计假设是你用动态库。静态库这条路是“能用但不好用”，很多地方需要手动干预。如果项目允许，优先考虑用 TensorFlow Lite 或者 ONNX Runtime 的静态库方案，它们的构建系统对静态链接的支持更友好。
另一个经验是，编译 TensorFlow 静态库最好在一台专门的构建机上做，把编译产物缓存起来。因为完整编译一次的时间成本太高，如果每个开发人员都在自己机器上编译，效率极低。可以用 CI 系统定期构建，把生成的静态库和头文件打包成压缩包，开发人员直接下载使用。
后续如果要做进一步优化，可以研究一下用bazel build --config=monolithic配合自定义的cc_binary规则，把业务代码和 TensorFlow 静态库一起构建。这样 Bazel 可以自动处理头文件路径和链接顺序，比手动写 Makefile 省心很多。但前提是业务代码也要用 Bazel 管理，如果业务代码用的是 CMake 或者 Make，那就只能手动集成了。
最后分享一个小技巧：在链接静态库时，如果遇到莫名其妙的符号冲突，可以用-Wl,--allow-multiple-definition让链接器忽略重复定义。这个选项有风险，可能导致运行时行为不确定，但在排查阶段可以用来快速定位是哪个符号冲突。定位到之后，再针对性地解决，比如用objcopy把冲突的符号重命名。
