Nginx交叉编译实战：从Ubuntu20.04到ARM64 Linux的完整移植记录
Nginx交叉编译实战：从Ubuntu20.04到ARM64 Linux的完整移植记录
在嵌入式开发和边缘计算场景中，将高性能Web服务器Nginx移植到ARM64架构的需求日益增长。无论是物联网网关、智能摄像头还是工业控制设备，都需要轻量级但功能完整的Web服务能力。本文将手把手带你完成从x86 Ubuntu环境到ARM64开发板的完整交叉编译过程，涵盖工具链配置、依赖库处理、模块定制等关键环节。
1. 环境准备与工具链配置
1.1 基础环境搭建
推荐使用Ubuntu 20.04 LTS作为编译主机，其软件仓库对交叉编译工具支持较为完善。首先更新系统并安装基础工具：
sudo apt update && sudo apt upgrade -y sudo apt install -y build-essential git wget tar1.2 交叉编译器选择
针对ARM64架构，常用的工具链有：
| 工具链名称 | 维护方 | 特点 |
|---|---|---|
| gcc-aarch64-linux-gnu | Ubuntu官方 | 安装简单，版本较旧 |
| Linaro GCC | Linaro组织 | 针对ARM优化，性能更好 |
| ARM官方工具链 | ARM公司 | 最新特性支持最完整 |
以安装Ubuntu官方工具链为例：
sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu验证安装：
aarch64-linux-gnu-gcc -v提示：如果目标板使用特定内核版本，建议选择与之匹配的工具链版本以避免兼容性问题。
2. 源码获取与预处理
2.1 下载核心组件
创建统一的工作目录并下载所需源码：
mkdir ~/nginx_cross && cd ~/nginx_cross wget http://nginx.org/download/nginx-1.25.3.tar.gz git clone https://github.com/arut/nginx-rtmp-module.git wget https://www.openssl.org/source/openssl-3.1.4.tar.gz wget https://sourceforge.net/projects/pcre/files/pcre2/10.42/pcre2-10.42.tar.gz wget https://zlib.net/zlib-1.3.tar.gz2.2 源码解压与目录结构
解压所有源码包并建立清晰的目录结构：
tar -xzf nginx-1.25.3.tar.gz tar -xzf openssl-3.1.4.tar.gz tar -xzf pcre2-10.42.tar.gz tar -xzf zlib-1.3.tar.gz mkdir -p nginx-1.25.3/install3. 交叉编译配置
3.1 修改Nginx编译脚本
进入Nginx源码目录，需要修改两处关键配置：
- 注释掉auto/cc/name文件中导致编译中断的检查：
sed -i '21s/exit 1/#exit 1/' auto/cc/name- 调整auto/types/sizeof中的类型检测：
sed -i '15s/ngx_size=.*/ngx_size=4/' auto/types/sizeof sed -i '36s/$CC/gcc/' auto/types/sizeof sed -i '43s/ngx_size=$NGX_AUTOTEST/ngx_size=4/' auto/types/sizeof3.2 配置编译参数
执行configure脚本时需特别注意路径参数：
cd nginx-1.25.3 ./configure \ --prefix=$(pwd)/install \ --with-cc=aarch64-linux-gnu-gcc \ --with-cc-opt="-Wno-error -Wno-deprecated-declarations" \ --with-cpp=aarch64-linux-gnu-g++ \ --with-http_ssl_module \ --with-http_mp4_module \ --with-http_v2_module \ --without-http_upstream_zone_module \ --with-openssl=../openssl-3.1.4 \ --with-openssl-opt="--cross-compile-prefix=aarch64-linux-gnu- linux-aarch64" \ --with-pcre=../pcre2-10.42 \ --with-zlib=../zlib-1.3 \ --add-module=../nginx-rtmp-module关键参数说明：
--with-cc：指定交叉编译器--with-openssl：OpenSSL源码路径--add-module：添加RTMP流媒体模块
4. 编译与安装
4.1 解决依赖编译
首先需要交叉编译各个依赖库：
# 编译PCRE2 cd ../pcre2-10.42 ./configure --host=aarch64-linux-gnu --prefix=$(pwd)/install make && make install # 编译OpenSSL cd ../openssl-3.1.4 ./Configure linux-aarch64 --cross-compile-prefix=aarch64-linux-gnu- make4.2 编译Nginx主体
返回Nginx目录执行编译：
cd ../nginx-1.25.3 make -j$(nproc) make install验证生成的二进制文件：
file install/sbin/nginx # 应显示：ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked...5. 目标板部署与验证
5.1 文件系统准备
将编译好的Nginx文件打包传输到开发板：
tar -czf nginx_arm64.tar.gz install/ scp nginx_arm64.tar.gz user@target_board:/tmp在开发板上解压并部署：
tar -xzf /tmp/nginx_arm64.tar.gz -C /usr/local/ ln -s /usr/local/install/sbin/nginx /usr/sbin/nginx mkdir -p /etc/nginx cp -r /usr/local/install/conf/* /etc/nginx/5.2 服务测试
启动Nginx并验证：
nginx -t # 测试配置 nginx # 启动服务 curl http://localhost # 验证响应对于RTMP模块的额外测试：
ffmpeg -re -i test.mp4 -c copy -f flv rtmp://localhost/live/stream6. 常见问题排查
6.1 动态链接库缺失
若运行时出现库缺失错误，可通过以下方式解决：
# 在开发板上查找缺失的库 ldd /usr/sbin/nginx # 从工具链中复制所需库 cp /path/to/toolchain/aarch64-linux-gnu/libc/lib/* /usr/lib/6.2 内核特性不兼容
如果遇到shmem等系统调用问题，可尝试：
- 修改内核配置重新编译
- 在nginx配置中禁用相关特性：
events { use epoll; accept_mutex off; }6.3 性能调优建议
针对ARM64架构的优化配置：
worker_processes auto; events { worker_connections 1024; multi_accept on; } http { sendfile on; tcp_nopush on; keepalive_timeout 65; gzip on; gzip_types text/plain application/json; }移植过程中最耗时的往往是依赖库的交叉编译环节。建议先单独验证每个依赖库的交叉编译结果，最后再整合到Nginx的主编译过程中。对于生产环境，可以考虑使用Buildroot或Yocto构建完整的定制化文件系统。