企业官网建设流程全解析

1. 为什么 Ubuntu 20.04 上装 aarch64 交叉工具链这么容易翻车

先交代一下背景。我平时主要做 ARM 平台上的嵌入式开发，宿主机是 Ubuntu 20.04，目标平台是 RK3588 这类 ARMv8 板子。刚开始接触交叉编译时，我以为“装个交叉编译器”就是apt install gcc-aarch64-linux-gnu一把梭，结果一编译就报错，而且错得五花八门——有的说找不到头文件，有的说动态链接器路径不对，甚至还有直接提示gcc: fatal error: cannot compute C compiler version的。后来摸索了一段时间，才把整套工具链的安装、配置和排错路径理顺。

这篇东西不是官方文档的复读，是我自己反复踩坑之后的记录。里面写的每一步、每一个报错，基本都能在真实环境中复现，尤其是那些“装完了但还是用不了”的隐蔽问题，我会把排查过程和原理一起讲清楚，希望能帮你省掉我当初浪费的那几天。

先说一个很重要的认知：在 Ubuntu 20.04 上装 aarch64 交叉编译工具链，核心其实不是“装”这个动作，而是“让工具链找到正确的 sysroot 和头文件搜索路径”。很多人装完gcc-aarch64-linux-gnu之后，随便写个 hello.c 一编就过，就以为大功告成，等到真去编译带依赖的工程时，才发现根本不是那么回事。

2. 快速安装：两条路线，按需选择

2.1 路线一：一条 apt 命令装完基础工具链

如果你是第一次接触交叉编译，或者只是临时需要在 x86_64 的 Ubuntu 上编一个 ARM64 的静态程序，那么官方源里的软件包是最稳妥的选择。Ubuntu 20.04（Focal）的官方源里已经收录了完整的 aarch64 交叉编译工具链，不需要添加任何第三方 PPA。

sudo apt update sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

这两条命令会安装：

• aarch64-linux-gnu-gcc：C 交叉编译器
• aarch64-linux-gnu-g++：C++ 交叉编译器
• 配套的cpp、gcc-ar、gcc-nm、gcc-ranlib等工具
• 基础 C/C++ 运行库的头文件和库文件

装完之后查一下版本，确认可用：

aarch64-linux-gnu-gcc --version

如果你看到类似aarch64-linux-gnu-gcc (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0的输出，就说明编译器本体已经装好了。

但这里有一个非常容易忽略的点：官方源里的这个包，C 库头文件是不完整的。它依赖libc6-dev-arm64-cross，而 Ubuntu 20.04 的libc6-dev-arm64-cross版本可能是 2.31 的某个修订版，这套 C 库的头文件相对完整，但如果你要编依赖libssl-dev、libz-dev这类第三方库的程序，就需要额外安装对应的arm64版本开发包，否则编译时直接报fatal error: openssl/ssl.h: No such file or directory。

2.2 路线二：手动部署官方 Linaro/GCC 工具链

如果你对编译器版本有要求，比如项目指定要用 GCC 10 或更高版本，或者你需要带aarch64-linux-gnu-gdb调试器、aarch64-linux-gnu-objdump等全套 binutils，那我建议你直接下载 ARM 官方提供的预编译工具链，而不是依赖 apt。

目前比较常用的是 ARM 的 GNU Toolchain 页面（developer.arm.com/downloads/-/arm-gnu-toolchain-downloads），选择AArch64 GNU/Linux target (aarch64-none-linux-gnu)或AArch64 GNU/Linux target with hard float (aarch64-none-linux-gnu)_x86_64的 tarball。

下载解压后，把bin目录加入PATH：

wget https://developer.arm.com/-/media/Files/downloads/gnu/11.2-2022.02/binrel/gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz tar -xf gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz export PATH=$PATH:$PWD/gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu/bin

手动部署的工具链，编译器前缀是aarch64-none-linux-gnu-，和 apt 版的前缀aarch64-linux-gnu-不一样，所以 Makefile 里的CROSS_COMPILE变量要写对。这个也是新手最容易搞混的地方——你明明装好了，但 make 的时候报command not found，先检查一下前缀是否匹配。

两种路线的区别我用一张表总结一下：

我个人建议：优先用 apt，除非你的项目明确需要新版 GCC。为什么？因为 apt 版和 Ubuntu 的库打包体系是绑定的。你装第三方开发库时，直接apt install libssl-dev:arm64就能装到交叉编译需要的 sysroot 里，路径都是标准的/usr/aarch64-linux-gnu。而手动部署的工具链，要自己把各类依赖库塞进它的 sysroot，工作量反而更大。

3. 安装完成只是开始：环境变量与 sysroot 路径

装完交叉编译器，你还需要告诉系统“这个编译器该去哪里找目标平台的库”。这里涉及一个核心概念：sysroot。

通俗地讲，sysroot 就是目标设备（比如 ARM 板子）上根目录的一个镜像，里面放着头文件、C 运行库、动态链接器、各种 .so 文件。交叉编译器在编译时必须基于这个 sysroot，而不是本机的/usr/include、/usr/lib——因为本机是 x86_64 的库，ARM 的可执行文件根本用不了。

apt 版工具链的 sysroot 路径是/usr/aarch64-linux-gnu。你可以看一下这个目录下有什么：

ls /usr/aarch64-linux-gnu

正常情况下你会看到bin、include、lib等子目录，其中lib里还有ld-linux-aarch64.so.1、libc.so.6这类目标平台的核心运行库。

关键点来了：交叉编译器默认会使用/usr/aarch64-linux-gnu作为 sysroot，但你用常规的 gcc 参数编译时，它还会去查找默认的头文件搜索路径。如果 Makefile 里硬编码了-I/usr/include或者-L/usr/lib，那你就会看到类似“头文件找到但架构不匹配”的诡异报错。为了避免这个问题，建议编译时显式指定 sysroot：

aarch64-linux-gnu-gcc --sysroot=/usr/aarch64-linux-gnu -o hello hello.c

如果是 C++ 工程，记得把库路径也指过去：

aarch64-linux-gnu-g++ --sysroot=/usr/aarch64-linux-gnu -I/usr/aarch64-linux-gnu/include -L/usr/aarch64-linux-gnu/lib -o hello hello.cpp

另外，建议给编译器配置一对符号链接，方便 Makefile 统一引用名字：

sudo ln -s /usr/bin/aarch64-linux-gnu-gcc /usr/bin/aarch64-linux-gnu-cc sudo ln -s /usr/bin/aarch64-linux-gnu-g++ /usr/bin/aarch64-linux-gnu-c++

很多内核模块、U-Boot 的构建脚本里写的是CC=aarch64-linux-gnu-cc，不建这个软链接，你会在 make 的第一步就收到一堆No such file or directory的提示。

4. 验证工具链：写个 hello world，交叉编译并检查产物

装没装好，不靠版本号，靠能不能编出能在目标平台运行的程序。我们做一个最简单也最有效的验证流程。

先在宿主机上建一个测试目录：

mkdir ~/arm64-test && cd ~/arm64-test

写一个简单的 C 文件：

#include <stdio.h> int main(void) { printf("Hello, aarch64!\n"); return 0; }

然后交叉编译：

aarch64-linux-gnu-gcc -o hello hello.c

下一步是验证产物确实不是本机可执行的。用file命令看格式：

file hello

你应该看到类似这样的输出：

hello: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 3.7.0, not stripped

这里有两个关键信息：

1. ARM aarch64：说明是 ARM64 架构的 ELF。
2. interpreter /lib/ld-linux-aarch64.so.1：说明它是动态链接的，运行时需要目标设备上有这个动态链接器。

如果你在 x86_64 的 Ubuntu 上直接执行./hello，会收到一个为人熟知的报错：

bash: ./hello: cannot execute binary file: Exec format error

看到这个报错不要慌，这恰恰说明你交叉编译成功了。因为你是在 x86_64 上尝试执行 ARM64 的程序，内核直接拒绝执行。要真正跑这个程序，要么拷贝到 ARM 板子上，要么用 qemu-aarch64 用户态模拟：

sudo apt install qemu-user qemu-aarch64 ./hello

如果输出Hello, aarch64!，那说明这个 hello world 从编译到运行链路全部打通了。

5. 常见错误一：fatal error: bits/libc-header-start.h: No such file or directory

这个报错几乎是嵌入式新手必遇的第一个拦路虎。错误输出长这样：

aarch64-linux-gnu-gcc -o test test.c test.c:1:10: fatal error: bits/libc-header-start.h: No such file or directory 1 | #include <stdio.h> | ^~~~~~~~~ compilation terminated.

为什么会出现这个错？核心原因是 apt 安装的gcc-aarch64-linux-gnu不会自动把 C 库头文件装全。bits/libc-header-start.h这个文件实际属于libc6-dev-arm64-cross这个包，而不是 gcc 包本身。所以在便编译的早期阶段，编译器去系统头文件搜索路径里找不到这个文件，就会报错。

解决办法很简单，把缺失的依赖补上：

sudo apt install libc6-dev-arm64-cross

装完后，你在/usr/aarch64-linux-gnu/include目录下应该能看到gnu/stubs.h、bits/libc-header-start.h等文件。

但如果你装完了还是报同样的错，可以手动检查一下头文件搜索路径：

aarch64-linux-gnu-gcc -v -E -x c /dev/null 2>&1 | grep "^ "

这条命令会把交叉编译器默认的头文件搜索路径逐行打印出来。正常情况下，你会看到/usr/aarch64-linux-gnu/include被列在 C 库头文件搜索路径里。如果没有，大概率是你系统里有多个版本的 GCC 或者手动部署过交叉工具链，把路径配置搞乱了。这时候直接显式指定--sysroot是最快的规避手段。

6. 常见错误二：cannot find -lgcc / cannot find -lc

这个报错通常在编译稍微复杂一点的程序时出现。报错信息长这样：

/usr/lib/gcc-cross/aarch64-linux-gnu/9/../../../../aarch64-linux-gnu/bin/ld: cannot find -lgcc collect2: error: ld returned 1 exit status

这个问题的本质是：编译器找到了，但它默认链接的库搜索路径里没有libgcc.a或者libc.a。原因是 libgcc 是编译器自带的库，交叉版本不一定随 gcc 包一并安装到默认库路径下。

排查思路是这样：

第一步，安装gcc-9-aarch64-linux-gnu-base和libgcc-9-dev-arm64-cross，把 libgcc 补上：

sudo apt install gcc-9-aarch64-linux-gnu-base libgcc-9-dev-arm64-cross

第二步，确认 libgcc.a 的真实路径：

find /usr -name "libgcc.a" 2>/dev/null | grep aarch64

我遇到过的情况是，libgcc.a 实际在/usr/lib/gcc-cross/aarch64-linux-gnu/9/下，但系统默认搜索路径却漏掉了它。这时候可以用-B参数把 GCC 子目录加进搜索路径：

aarch64-linux-gnu-gcc -B/usr/lib/gcc-cross/aarch64-linux-gnu/9/ -o test test.c

不过更推荐的做法是，检查一下你的 Makefile 或者编译命令里是不是用了-nostdlib或-nodefaultlibs。有些嵌入式工程为了精简体积，在某个环节会加这些参数，结果把默认 libgcc 也去掉了，但后面又没手动链进去。正确做法是在链接命令尾部自动补一句-lgcc -lc，比如：

aarch64-linux-gnu-gcc -nostdlib -o test test.o -lgcc -lc

libgcc 里面包含了一些编译期辅助函数，比如__aeabi_uidiv（除法）、__aeabi_ldivmod（长除法）这些，链接裸机或内核代码时必须显式拉进来，否则就是 cannot find 或者 undefined reference。

7. 常见错误三：动态链接器路径不对导致 target 上无法运行

这种情况最坑，因为它不会在编译时报任何错误，你编出来一个看似正常的 ARM64 可执行文件，拷到板子上运行时，却得到：

/lib/ld-linux-aarch64.so.1: No such file or directory

如果你是在一个精简的 ARM64 根文件系统（比如用 busybox 构建的最小系统）上测试，可能会遇到这个问题，因为系统里的实际动态链接器并不在那个默认路径。

先检查编译后的可执行文件依赖了哪个动态链接器：

readelf -l hello | grep interpreter

输出可能是：

INTERP 0x0000000000000238 0x0000000000000238 0x0000000000000238 0x0000000000000019 0x0000000000000019 R 0x8

或者直接看：

readelf -l hello | grep interpreter -A1

如果显示[Requesting program interpreter: /lib/ld-linux-aarch64.so.1]，而你的目标系统上该文件存在于/lib64/ld-linux-aarch64.so.1或其它自定义路径，那么编译时就需要用-Wl,--dynamic-linker把它改成正确的路径：

aarch64-linux-gnu-gcc -Wl,--dynamic-linker=/lib64/ld-linux-aarch64.so.1 -o hello hello.c

这个方法在移植到特定嵌入式 rootfs 时特别常用。很多用 Yocto 或 Buildroot 构建的系统，rootfs 的目录布局都和 Ubuntu 不一样，总不能为了一个程序去改整个文件系统吧？直接编译时指定动态链接器路径反而干脆利落。

另外，还可能出现一种情况是一切路径都正确、但在板子上运行仍然报No such file or directory——这时候别急着怪交叉编译器。先检查一下宿主机上交叉编译出来的程序是被file识别为正确的架构，然后检查目标板子上的内核是否支持 ARM64 架构（废话，不支持的话根本启动不了）。更有可能的是目标 rootfs 里缺少必要的共享库，比如：

ldd hello # 在板子上执行

如果在板子上执行提示not a dynamic executable，那说明你可能不小心把静态链接和动态链接搞混了，或者hello不是真正的动态链接产物。

8. 常见错误四：头文件、库文件架构不匹配导致的诡异编译错误

这类问题的特点是：头文件找到了，但后面跟了一堆莫名其妙的undefined reference或者relocation truncated to fit。根本原因通常是——把 x86_64 的开发库头文件暴露给了 ARM 编译器，或者反过来。

举个例子。你为了图省事，在编译 C++ 工程时加了-I/usr/include/jsoncpp，这个目录下是 x86_64 平台的 JsonCpp 头文件，虽然源码头文件能读进去，但它内部声明的某些类型与交叉编译器内置类型不一致，最终链接时就会有一堆和std::相关的莫名报错。

正确做法是：对于交叉编译工程，所有第三方依赖都要安装 ARM64 版本。Ubuntu 20.04 的 apt 支持多架构安装：

sudo dpkg --add-architecture arm64 sudo apt update sudo apt install libssl-dev:arm64 libz-dev:arm64

dpkg --add-architecture arm64这个命令的作用是告诉 apt，除了 amd64，我还要安装 arm64 架构的软件包。执行后，libssl-dev:arm64这类带架构后缀的包才能被 apt 解析。

装完 arm64 版本的开发库后，相关头文件和库会安装到/usr/aarch64-linux-gnu/include和/usr/aarch64-linux-gnu/lib，交叉编译器在默认情况下是能感知到这些路径的，因为 apt 版工具链默认 sysroot 就是/usr/aarch64-linux-gnu。不过有些第三方库的头文件结构比较特殊，还需要手动加-I参数。这时候建议在编译命令的第一行加上-v，把实际搜索的头文件路径打出来，一旦路径里出现/usr/include且后面没跟/aarch64-linux-gnu，就要警惕架构污染了。

9. 常见错误五：libstdc++.so.6: cannot open shared object file

这个报错通常出现在目标板子运行时，而不是编译时。程序已经和宿主机上的交叉编译产物一样能跑了，但动态加载器找不到libstdc++.so.6。

这种情况比分两种：

拆开来看，一是程序是动态链接的，但 target 根文件系统里没有 libstdc++。

排查方法是在板子上执行：

find / -name "libstdc++.so.6" 2>/dev/null

如果找不到，那就说明你的 rootfs 里压根没有 C++ 标准库。如果你用的是 Buildroot 或 Yocto 构建的根文件系统，可以在配置里开启 C++ 支持；如果是手工搭建的 rootfs，可以直接从宿主机交叉工具链里拷：

sudo cp /usr/aarch64-linux-gnu/lib/libstdc++.so.6* /你的目标rootfs/usr/lib/

注意：最好用arm64架构的 libstdc++，别把 x86_64 系统的拷过去。可以通过file验证架构：

file /usr/aarch64-linux-gnu/lib/libstdc++.so.6

拆开来看，二是程序在编译时链接的 libstdc++ 路径，与运行时不符。

如果你平时会用-L参数指定库搜索路径（比如有些手动部署的工具链放在/opt/toolchain/lib），链接时用了/opt/toolchain/lib/libstdc++.so.6，运行时却去/usr/lib找，就会找不到。这时建议在链接时用-Wl,-rpath把库的搜索路径写进最终可执行文件里：

aarch64-linux-gnu-g++ -o app app.o -L/opt/toolchain/lib -lstdc++ -Wl,-rpath,/opt/toolchain/lib

我见过很多搞嵌入式的人，在开发主机上程序跑得好好的，一部署到板子就报 libstdc++ not found，最后查半天发现是 rootfs 里压根没有。说实话，交叉编译的“最后一公里”，经常就死在这种看似不搭边的运行环境问题上。

10. 实战案例：给 CMake 工程配置交叉编译

很多新手直接用 gcc 命令编译几个文件还好，一旦工程大了，必然要上 CMake。给 CMake 写工具链文件也是交叉编译的经典步骤，一不小心就会踩坑。

先写一个工具链文件，比如aarch64-linux-gnu.cmake：

set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR aarch64) set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc) set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++) set(CMAKE_FIND_ROOT_PATH /usr/aarch64-linux-gnu) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

这里三个MODE变量的设置非常关键，解释一下：

• CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER：查找程序时不去交叉根目录找，因为编译期用的工具（比如 cmake、编译器自身）都是 x86_64 的，必须在主机上找。
• CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY：查找库时只能从交叉根目录找，禁止找到宿主机 x86_64 的.so和.a。
• CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY：查找头文件同理。

如果你漏了后面这两行，CMake 很容易通过find_package找到宿主机/usr/lib/x86_64-linux-gnu下的库，然后编出来的程序架构全乱。

使用时：

mkdir build && cd build cmake -DCMAKE_TOOLCHAIN_FILE=../aarch64-linux-gnu.cmake .. make

添加一个额外提示：CMAKE_FIND_ROOT_PATH可以指定多个路径，如果你们团队的库统一安装在/opt/arm64-libs下，可以写成：

set(CMAKE_FIND_ROOT_PATH /usr/aarch64-linux-gnu /opt/arm64-libs)

这样 CMake 会在这两个目录下按顺序查找库和头文件。

11. 可能被忽略但必须注意的隐性坑

11.1 CC 环境变量与 Makefile 的交叉编译逻辑

有些工程 Makefile 写得很“标准”，已经支持CROSS_COMPILE变量。只要你这样传递：

make CROSS_COMPILE=aarch64-linux-gnu-

它就会自动调用aarch64-linux-gnu-gcc。但如果你遇到的代码库写死了gcc，那你只能手动改 Makefile 或构造一个 shim：

mkdir -p ~/bin printf '#!/bin/bash\nexec aarch64-linux-gnu-gcc "$@"\n' > ~/bin/gcc chmod +x ~/bin/gcc export PATH=~/bin:$PATH

这个方案不太优雅，但是很多老嵌入式工程确实只能这样绕。另一种更干净的办法是直接改 Makefile 里的CC：

CC = aarch64-linux-gnu-gcc

如果工程里分别用了CC、AR、LD等变量，则要一并替换：

AR = aarch64-linux-gnu-ar LD = aarch64-linux-gnu-ld OBJCOPY = aarch64-linux-gnu-objcopy

11.2 32 位依赖和 64 位目标的混淆

Ubuntu 20.04 上如果同时装了 i386 体系的多架构库，偶尔会出现“某库路径在两个架构下都有”的情况。交叉编译时，编译器只看自己的 sysroot，所以一般不会被宿主机 i386 或 amd64 干扰。但如果你用 apt 装了libc6-dev-i386，别慌，它不影响。真正要防的是在 CMake 或 Makefile 里直接写死/usr/lib。这种硬编码路径，才是交叉编译的头号杀手。

11.3 使用 Clang 作为交叉编译前端的替代方案

如果你觉得 GCC 系交叉工具链某些报错看不懂，也可以试试 Clang。Ubuntu 20.04 的 Clang 对交叉编译支持得不错:

sudo apt install clang lld clang --target=aarch64-linux-gnu -gcc-toolchain /usr -o hello hello.c

加粗显示一下：--target=aarch64-linux-gnu是给 Clang 指定目标平台的关键参数。Clang 本身是天然支持多目标的，但需要找到对应的 sysroot 和 GCC 工具链中的库文件。这个方案在交叉编译 C++ 依赖较多的代码时有时反而更省心。

12. 安装后的一套速查命令

把自己常用的一套交叉工具链速查命令放在下面，能帮你快速定位问题：

# 查看交叉编译器版本和默认目标 aarch64-linux-gnu-gcc -v 2>&1 | grep Target # 查看头文件搜索路径 aarch64-linux-gnu-gcc -v -E -x c /dev/null 2>&1 | grep "^ " # 查看库搜索路径 aarch64-linux-gnu-gcc -print-search-dirs # 查看 sysroot 路径 aarch64-linux-gnu-gcc -print-sysroot # 查看默认库路径 aarch64-linux-gnu-gcc -print-file-name=libc.so # 检查可执行文件依赖哪些动态库 aarch64-linux-gnu-readelf -d hello | grep NEEDED # 检查可执行文件解释器路径 aarch64-linux-gnu-readelf -l hello | grep interpreter

这组命令里面有相当一部分是诊断“编译出来的程序能不能在目标系统跑”的关键手段。我在实际调试板子上的程序加载失败时，几乎全靠 readelf 这一条来确定是不是动态库依赖问题。

13. 最后的实际体会

交叉编译工具链本身并不神秘，本质就是“一个在 x86 上运行的编译器，编译出 ARM 架构的机器码”。而 Ubunutu 20.04 上这套gcc-aarch64-linux-gnu的真正难点，不是装，而是装完之后的 sysroot、依赖库、路径配置这些容易被忽略的工程化问题。我自己的习惯是，每次新搭一台开发环境，先花十分钟从头跑一遍 hello world 验证，再往里加工程化的依赖——这个土办法虽然看起来慢，但在后面用起来反而最省时间。

还有一个心得很想分享：很多人在交叉编译遇到诡异报错时，第一反应是上网复制粘贴命令，或者去找所谓的“魔法参数”，但其实大多数问题都能靠-v和readelf这两条最基本的命令定位出来。与其迷信某条命令能解决一切，不如先搞清楚你的交叉编译器到底在搜哪些路径，再根据报错信息逐项核对。

上面这些都是我在 Ubuntu 20.04 上折腾交叉编译的真实记录，覆盖面从安装命令、验证方式到几个最常见的报错排查，应该能帮你少走不少弯路。如果你在配置过程中还遇到其他报错，建议先跑一遍那组速查命令，把编译器的实际搜索路径和产物状态摸清楚，然后再针对性地查，会比盲目折腾高效得多。