Windows下WSL2交叉编译arm64 deb包实战指南

1. 为什么要在 Windows 上折腾 arm64 的 deb 包先说清楚这件事的来龙去脉。你手头有一块 arm64 的开发板——可能是树莓派、香橙派、瑞芯微的板子也可能是国产化平台上的工控机——上面跑的是 Debian 系或者 Ubuntu 系的系统包管理用的是 dpkg/apt。你在 Windows 上写代码、调试、编译习惯了 VS Code 加 Windows Terminal 这套组合不想为了打个包专门再开一台 Linux 物理机或者装双系统。于是问题就变成了怎么在 Windows 环境下产出一个能在 arm64 板子上直接dpkg -i安装的 deb 包这个需求听起来小众实际上非常普遍。做嵌入式、做边缘计算、做国产化适配的团队开发机大概率是 Windows目标机大概率是 arm64 Linux。中间这条“编译—打包—部署”的链路如果每次都要手动拷贝、手动 scp、手动解压效率低到让人抓狂。而如果能把整条链路收敛到 Windows 上用 WSL 做交叉编译环境最后在板子上敲一行dpkg -i xxx.deb就完事那体验是完全不一样的。我自己的场景是Windows 11 主力开发机WSL2 里跑 Ubuntu 22.04目标板是 arm64 架构的 Debian 11。项目里有 C 写的守护进程、Python 写的辅助脚本、还有几个 systemd unit 文件需要打成一个 deb 包安装后自动注册服务、自动创建用户、自动处理配置文件。这套流程我前前后后踩了不少坑从“编译出来的二进制在板子上跑不起来”到“dpkg 报依赖错误”再到“postinst 脚本执行失败导致安装中断”基本把能踩的雷都踩了一遍。这篇文章就是把这套流程完整拆开从 WSL 环境准备、交叉编译工具链配置、deb 包目录结构设计、control 文件编写、到最终在板子上dpkg -i验证每一步都讲清楚为什么这么做、怎么做、以及我踩过的坑。适合两类人看一类是刚接触 arm64 交叉编译和 deb 打包的新手另一类是在 Windows 上做嵌入式开发、想优化部署流程的老手。不管你是哪种只要跟着走一遍应该能省下不少查文档和试错的时间。提示本文所有操作都在 Windows 11 WSL2 Ubuntu 22.04 环境下验证过目标平台为 arm64 Debian 11。其他发行版和架构组合思路一致细节参数需要按实际情况调整。2. 环境准备WSL2 与交叉编译工具链的选型逻辑2.1 WSL2 安装与磁盘位置调整WSL 的安装现在简单到一行命令。以管理员身份打开 PowerShell执行wsl --install -d Ubuntu-22.04装完之后重启系统会让你设置 Linux 用户名和密码。默认情况下WSL 的虚拟磁盘文件ext4.vhdx放在 C 盘的用户目录下路径大概是C:\Users\你的用户名\AppData\Local\Packages\CanonicalGroupLimited...\LocalState\。这个位置有个问题C 盘空间通常比较紧张而交叉编译工具链加上源码、中间产物很容易吃掉几十个 G。所以我的习惯是第一时间把 WSL 迁移到 D 盘或者其他数据盘。迁移的方法不复杂但步骤要记清楚。先关闭 WSLwsl --shutdown然后导出当前发行版为 tar 文件wsl --export Ubuntu-22.04 D:\wsl\ubuntu22.tar导出完成后注销原来的发行版wsl --unregister Ubuntu-22.04接着在目标位置重新导入mkdir D:\wsl\ubuntu22 wsl --import Ubuntu-22.04 D:\wsl\ubuntu22 D:\wsl\ubuntu22.tar --version 2导入之后默认登录用户会变成 root需要手动改回普通用户。在 WSL 里执行echo -e [user]\ndefault你的用户名 /etc/wsl.conf然后wsl --shutdown再重新进入用户就恢复成你自己了。这一步我踩过的坑是导出前一定要确认没有正在运行的编译任务否则 tar 文件可能不完整导入后各种奇怪报错。注意WSL2 的磁盘迁移不是必须的但如果你打算长期在 Windows 上做 arm64 交叉编译强烈建议把 WSL 放到空间充足的盘符。我见过太多人 C 盘爆红之后手忙脚乱。2.2 交叉编译工具链的选择在 WSL 里编译 arm64 的二进制核心是选对工具链。Debian/Ubuntu 仓库里现成的交叉编译器有好几套常见的有工具链包名目标架构适用场景我的评价gcc-aarch64-linux-gnuarm64通用 Linux 用户态程序最常用推荐首选gcc-arm-linux-gnueabihfarmhf32 位 ARM 硬浮点老板子才用gcc-arm-none-eabiarm裸机/RTOS不跑 Linux 不用这个g-aarch64-linux-gnuarm64C 程序和上面配套装安装命令很直接sudo apt update sudo apt install -y gcc-aarch64-linux-gnu g-aarch64-linux-gnu装完之后验证一下aarch64-linux-gnu-gcc --version如果输出了版本信息说明工具链就位。这里有个细节工具链的前缀是aarch64-linux-gnu-不是arm64-linux-gnu-。很多新手第一次找命令找不到就是因为把架构名和工具链前缀搞混了。arm64 是 Debian 的架构命名aarch64 是 GNU 工具链的命名两者指的是同一个东西。2.3 为什么不用 QEMU 模拟编译有人会问既然 WSL 里可以装 QEMU为什么不直接在 QEMU 里跑一个 arm64 的 Ubuntu然后在里面原生编译这样就不用交叉编译了。我的答案是可以但没必要而且慢。QEMU 用户态模拟的性能损耗很大编译一个中等规模的项目原生 x86 可能两分钟QEMU 模拟 arm64 可能要二十分钟。交叉编译虽然配置麻烦一点但编译速度是原生的而且产出的二进制质量更可控。QEMU 更适合做运行验证比如你想在 WSL 里先跑一下 arm64 的二进制看看能不能启动可以用qemu-aarch64-static配合binfmt来做但编译环节还是交给交叉工具链更划算。提示如果你确实需要 QEMU 做运行验证可以装qemu-user-static然后注册 binfmtsudo apt install qemu-user-static binfmt-support。这样 arm64 的二进制在 WSL 里可以直接执行底层走 QEMU 模拟。但记住这只是验证手段不是编译手段。3. deb 包结构设计与 control 文件编写要点3.1 deb 包的目录骨架deb 包本质上就是一个 ar 归档里面包含两个 tar 包control.tar.gz和data.tar.gz。但手动构造 ar 归档太原始了实际工作中我们用dpkg-deb --build来打包只需要准备好一个符合规范的目录结构。标准的 deb 构建目录长这样myapp/ ├── DEBIAN/ │ ├── control │ ├── postinst │ ├── prerm │ ├── postrm │ └── conffiles └── usr/ ├── bin/ │ └── myapp ├── lib/ │ └── systemd/ │ └── system/ │ └── myapp.service └── share/ └── myapp/ └── config.yamlDEBIAN目录存放的是包的元数据和控制脚本usr目录下的内容会被原样解压到目标系统的根目录。也就是说usr/bin/myapp最终会出现在板子的/usr/bin/myapp。这里的关键点是目录结构必须严格按照目标系统的绝对路径来组织。你不能在包里写./bin/myapp因为安装时它会被放到/bin/myapp而不是你期望的位置。我见过有人把文件放在opt/下结果 postinst 脚本里写的路径和实际安装路径对不上服务起不来。3.2 control 文件逐字段拆解DEBIAN/control是 deb 包的核心元数据文件格式是 RFC822 风格的键值对。一个典型的 control 文件Package: myapp Version: 1.0.0 Architecture: arm64 Maintainer: Your Name youexample.com Depends: libc6 ( 2.31), libssl1.1 Section: utils Priority: optional Homepage: https://example.com Description: A sample application for arm64 boards This is a longer description that can span multiple lines. Each line after the first must start with a space.逐字段说明Package包名只能用小写字母、数字、加号、减号、点号。不能有大写字母不能有下划线。我踩过的坑是包名里带了驼峰dpkg-deb --build直接报错。Version版本号建议遵循主版本.次版本.修订号的格式。如果需要加构建信息可以用1.0.0-1这种形式横线后面是 Debian 修订号。Architecture这里必须写arm64。如果你写amd64板子上dpkg -i会直接拒绝安装报架构不匹配。如果你想让包在所有架构上都能装可以写all但前提是包里没有架构相关的二进制。Depends依赖列表逗号分隔。这里写的包名必须是目标系统仓库里存在的。如果依赖写错了dpkg -i会报依赖不满足安装失败。我的经验是尽量少写依赖能用静态链接就静态链接减少部署时的麻烦。Description描述字段第一行是简短描述后续行以空格开头作为详细描述。这个字段在dpkg -l和apt show里会显示写清楚有助于后期维护。注意Depends字段里的版本约束要谨慎使用。比如你写了libc6 ( 2.31)但板子上的 libc 是 2.28那安装就会失败。交叉编译时链接的 libc 版本要和目标系统匹配否则即使装上了也跑不起来。3.3 交叉编译时如何控制 libc 版本这是交叉编译 arm64 deb 包最容易翻车的地方。你的 WSL 里装的是 Ubuntu 22.04libc 版本是 2.35目标板子是 Debian 11libc 版本是 2.31。如果你直接用 WSL 里的交叉工具链编译链接的是 2.35 的 libc产出的二进制在板子上运行时会报./myapp: /lib/aarch64-linux-gnu/libc.so.6: version GLIBC_2.34 not found解决办法有两个方向方案一使用目标系统对应的 sysroot。从板子的系统里把/lib、/usr/lib、/usr/include打包出来作为交叉编译的 sysroot。编译时加--sysroot/path/to/sysroot参数。这个方案最干净但准备工作量大。方案二静态链接 libc。编译时加-static参数把 libc 直接编进二进制。这样产出的文件体积大一些但不依赖目标系统的 libc 版本。对于小型工具和守护进程我通常选这个方案省事。aarch64-linux-gnu-gcc -static -o myapp myapp.c方案三在 WSL 里装一个和目标系统同版本的交叉编译环境。比如用 Docker 跑一个 Debian 11 的 arm64 交叉编译容器。这个方案最彻底但引入了 Docker 依赖流程变重。我自己的选择是核心二进制静态链接Python 脚本和配置文件走普通打包。这样既避免了 libc 版本问题又保持了包的轻量。4. 从编译到打包的完整实操流程4.1 编译环节Makefile 与交叉编译参数假设我们有一个 C 写的守护进程myapp.c一个 systemd unit 文件myapp.service一个配置文件config.yaml。项目目录结构project/ ├── src/ │ └── myapp.c ├── debian/ │ ├── control │ ├── postinst │ ├── prerm │ └── myapp.service ├── config.yaml └── MakefileMakefile 里定义交叉编译工具链CC aarch64-linux-gnu-gcc CFLAGS -Wall -O2 -static TARGET myapp SRCS src/myapp.c $(TARGET): $(SRCS) $(CC) $(CFLAGS) -o $(TARGET) $(SRCS) clean: rm -f $(TARGET) .PHONY: clean执行make之后用file命令验证产出的二进制架构file myapp正确输出应该是myapp: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked, for GNU/Linux 3.7.0, not stripped如果看到x86-64说明工具链没生效检查 Makefile 里的CC变量是否被覆盖。如果看到dynamically linked说明-static没起作用检查 CFLAGS 是否传递到了编译命令。提示-static不是万能的。如果你的程序依赖了某些只能动态链接的库比如某些闭源驱动库那就必须走 sysroot 方案。静态链接只适合纯用户态、依赖简单的程序。4.2 构造 deb 目录树编译完成后开始构造 deb 包的目录树。我习惯在项目根目录下建一个build/deb目录作为打包工作区mkdir -p build/deb/DEBIAN mkdir -p build/deb/usr/bin mkdir -p build/deb/usr/lib/systemd/system mkdir -p build/deb/usr/share/myapp然后把文件拷贝到对应位置cp myapp build/deb/usr/bin/ cp debian/myapp.service build/deb/usr/lib/systemd/system/ cp config.yaml build/deb/usr/share/myapp/拷贝完成后设置权限。可执行文件必须是 755配置文件通常是 644chmod 755 build/deb/usr/bin/myapp chmod 644 build/deb/usr/share/myapp/config.yaml chmod 644 build/deb/usr/lib/systemd/system/myapp.service权限这块有个坑如果你在 Windows 文件系统上操作WSL 挂载的/mnt/d/目录默认权限是 777chmod 可能不生效。所以打包工作区一定要放在 WSL 的原生文件系统里比如~/build/不要放在/mnt/c/或/mnt/d/下。4.3 control 文件与维护脚本编写DEBIAN/control文件内容Package: myapp Version: 1.0.0 Architecture: arm64 Maintainer: Your Name youexample.com Depends: libc6 Section: utils Priority: optional Description: Sample arm64 application A sample daemon for arm64 boards, packaged as deb.DEBIAN/postinst脚本在安装完成后执行#!/bin/bash set -e # 创建运行用户如果不存在 if ! id -u myapp /dev/null 21; then useradd -r -s /usr/sbin/nologin myapp fi # 重新加载 systemd systemctl daemon-reload # 启用并启动服务 systemctl enable myapp.service systemctl start myapp.service exit 0DEBIAN/prerm脚本在卸载前执行#!/bin/bash set -e # 停止并禁用服务 systemctl stop myapp.service || true systemctl disable myapp.service || true exit 0脚本写完后必须加可执行权限chmod 755 build/deb/DEBIAN/postinst chmod 755 build/deb/DEBIAN/prerm注意postinst和prerm脚本里的set -e很重要。如果脚本中间某条命令失败没有set -e的话脚本会继续执行可能导致安装状态不一致。但也要小心set -e下如果某条命令返回非零比如systemctl stop一个不存在的服务脚本会直接退出导致安装失败。所以对于可能失败的命令要加|| true兜底。4.4 打包命令与验证一切就绪后执行打包dpkg-deb --build build/deb myapp_1.0.0_arm64.deb如果一切正常会输出dpkg-deb: building package myapp in myapp_1.0.0_arm64.deb.打包完成后先在 WSL 里做一次本地检查dpkg-deb --info myapp_1.0.0_arm64.deb dpkg-deb --contents myapp_1.0.0_arm64.deb--info会显示 control 文件的内容--contents会列出包内所有文件及其权限。重点检查Architecture 是否为 arm64文件路径是否正确./usr/bin/myapp而不是./bin/myapp权限是否正确可执行文件应该是-rwxr-xr-x如果这两步没问题就可以把 deb 包传到板子上了。5. 板子上的安装验证与常见问题排查5.1 传输与安装把 deb 包从 Windows 传到板子上方式很多。我常用的是scpscp myapp_1.0.0_arm64.deb userboard-ip:/tmp/然后在板子上执行sudo dpkg -i /tmp/myapp_1.0.0_arm64.deb如果依赖都满足会看到Selecting previously unselected package myapp. (Reading database ... 12345 files and directories currently installed.) Preparing to unpack /tmp/myapp_1.0.0_arm64.deb ... Unpacking myapp (1.0.0) ... Setting up myapp (1.0.0) ...安装完成后验证服务状态systemctl status myapp.service如果服务正常运行说明整条链路走通了。5.2 常见问题速查表现象可能原因排查方法解决方案dpkg: error processing archive: package architecture (amd64) does not match system (arm64)control 里 Architecture 写错dpkg-deb --info查看改成 arm64 重新打包dpkg: dependency problems prevent configurationDepends 里的包板子上没有apt-cache policy 包名减少依赖或先在板子上装依赖安装成功但服务起不来postinst 脚本没执行或执行失败systemctl status看日志检查 postinst 权限和内容GLIBC_2.34 not found交叉编译链接了高版本 libcldd myapp查看依赖静态链接或使用 sysrootExec format error二进制架构不对file myapp确认交叉工具链前缀正确postinst 里systemctl命令找不到板子系统没有 systemdwhich systemctl改用 SysV init 脚本或确认系统安装后配置文件被覆盖没有标记 conffiles检查 DEBIAN/conffiles把配置文件路径写入 conffiles5.3 我踩过的几个典型坑坑一WSL 文件系统权限问题。前面提过在/mnt/c/下 chmod 不生效导致打包出来的可执行文件权限是 777 或者 644板子上装完跑不起来。解决办法就是把整个打包工作区放在 WSL 原生目录下比如~/work/build/。坑二postinst 脚本换行符问题。在 Windows 上编辑的脚本文件换行符是 CRLF传到 WSL 里执行会报bad interpreter: /bin/bash^M。解决办法是用dos2unix转换或者在 VS Code 里把文件换行符设成 LF。我现在的习惯是所有 shell 脚本在 WSL 里用 vim 或者 nano 写避免从 Windows 侧拷贝。坑三dpkg 安装时 postinst 失败导致包处于半安装状态。这时候dpkg -i会报错而且包的状态是iF半配置。解决办法是先sudo dpkg --configure -a尝试重新配置如果还是失败就sudo dpkg --remove --force-remove-reinstreq myapp强制移除修好脚本后重新打包安装。坑四systemd 服务启动超时。postinst 里systemctl start如果服务启动慢dpkg 会卡住。我的做法是在 postinst 里只做systemctl enable不直接start让服务在下次重启时自动启动或者提示用户手动启动。这样安装过程更快也不容易因为服务启动失败导致安装失败。提示如果你在板子上反复安装调试可以用sudo dpkg -i --force-overwrite myapp_1.0.0_arm64.deb来覆盖安装避免文件冲突报错。但正式发布时不要用这个参数容易掩盖问题。6. 自动化打包脚本与持续优化建议6.1 一键打包脚本手动敲命令容易漏步骤我写了一个build_deb.sh放在项目根目录#!/bin/bash set -e APP_NAMEmyapp VERSION1.0.0 ARCHarm64 BUILD_DIRbuild/deb OUTPUT${APP_NAME}_${VERSION}_${ARCH}.deb # 清理旧构建 rm -rf build mkdir -p ${BUILD_DIR}/DEBIAN mkdir -p ${BUILD_DIR}/usr/bin mkdir -p ${BUILD_DIR}/usr/lib/systemd/system mkdir -p ${BUILD_DIR}/usr/share/${APP_NAME} # 编译 make clean make # 拷贝文件 cp ${APP_NAME} ${BUILD_DIR}/usr/bin/ cp debian/${APP_NAME}.service ${BUILD_DIR}/usr/lib/systemd/system/ cp config.yaml ${BUILD_DIR}/usr/share/${APP_NAME}/ # 拷贝控制文件 cp debian/control ${BUILD_DIR}/DEBIAN/ cp debian/postinst ${BUILD_DIR}/DEBIAN/ cp debian/prerm ${BUILD_DIR}/DEBIAN/ # 设置权限 chmod 755 ${BUILD_DIR}/usr/bin/${APP_NAME} chmod 644 ${BUILD_DIR}/usr/share/${APP_NAME}/config.yaml chmod 644 ${BUILD_DIR}/usr/lib/systemd/system/${APP_NAME}.service chmod 755 ${BUILD_DIR}/DEBIAN/postinst chmod 755 ${BUILD_DIR}/DEBIAN/prerm # 打包 dpkg-deb --build ${BUILD_DIR} ${OUTPUT} echo Package built: ${OUTPUT}这个脚本把编译、拷贝、权限设置、打包串成一条线每次改完代码执行./build_deb.sh就能产出新的 deb 包。脚本里的set -e保证任何一步失败都会立即停止不会产出半成品。6.2 版本号自动管理手动改版本号容易忘我后来改成从 git tag 或者环境变量读取VERSION${VERSION:-$(git describe --tags --always 2/dev/null || echo 0.0.0)}这样在 CI 环境里可以通过环境变量注入版本号本地开发时用 git tag 自动生成。control 文件里的 Version 字段也需要动态替换可以用sedsed -i s/^Version:.*/Version: ${VERSION}/ ${BUILD_DIR}/DEBIAN/control6.3 后续可以扩展的方向这套流程跑通之后还有几个可以继续优化的点。一是把打包脚本接入 CI比如 GitHub Actions 或者 GitLab CI每次打 tag 自动产出 deb 包并上传到制品库。二是如果目标板子支持 apt 仓库可以搭一个本地 apt 源把 deb 包放进去板子上直接apt install myapp比dpkg -i更优雅还能自动处理依赖。三是如果项目里有多个包可以引入dh_make和debuild这套 Debian 官方工具链虽然学习曲线陡一点但标准化程度更高。我个人在实际操作中的体会是交叉编译加 deb 打包这件事第一次配的时候麻烦但配好之后就是一条命令的事。关键是把工具链版本、libc 兼容性、脚本权限这几个点一次性搞对后面就是复制粘贴改改包名和版本号。最怕的是每次换一块新板子就重新摸索一遍所以我把这套流程整理成脚本和文档团队里新人来了直接照着跑省了很多沟通成本。最后再分享一个小技巧如果你不确定板子上的系统支持哪些依赖可以在板子上执行dpkg -l看看已安装的包列表或者用apt-cache depends 包名查依赖树。打包时 Depends 字段尽量只写板子上确定存在的包实在拿不准就静态链接用体积换省心。