从拿到一块 aarch64 的目标板到把 Qt5.14.2 通过静态交叉编译的方式跑起来这个过程我前前后后折腾了快两个星期。中间踩过的坑从工具链不匹配、sysroot 缺失到 openssl 静态库没编进去、xcb 插件加载失败每一个都能让新手卡上好几天。所以我把这套从零搭建 Qt5.14.2 aarch64 静态交叉编译环境的完整过程整理成手册包括每一步的命令、参数、路径规划以及我实际遇到的各种报错和处理方式。这篇文章适合正在做嵌入式 Linux 开发、需要把 Qt 应用部署到 ARM 平台、或者想把应用编译成单个独立可执行文件的朋友参考照着做基本能少走一半弯路。1. 为什么非要静态交叉编译1.1 动态库方案为什么不适合我们的场景先说说我为什么坚持用静态编译。大多数时候我们拿到一块 ARM 开发板第一反应是直接用板子自带的交叉编译工具链把 Qt 动态编译出来然后应用链接动态库部署的时候把一整套.so拷到板子上。这个方案在开发阶段确实没什么问题编译快、Qt 更新也不用重新编应用。但是到了产品化阶段问题就来了。首先是依赖链太乱。Qt 动态库本身就依赖一堆系统库像 libfontconfig、libdbus、libxkbcommon这些库在板子上不一定都有或者版本跟编译环境不一致。你辛辛苦苦拷过去运行的时候ldd一看还差一大串。其次是版本冲突。如果板子上还有别人编译的 Qt 程序用的 Qt 版本跟你不一致那动态库一覆盖对方立刻崩给你看。静态编译就完全绕开了这些。应用把 Qt 核心库、平台插件、第三方依赖统统打进了同一个二进制里部署的时候就是一个文件搞定。缺点是编译时间变长、可执行文件体积变大但对于生产环境来说稳定性和可维护性远比那几百 MB 的磁盘空间重要。我这次的场景是给一台 ARM 工控机上跑一个独立的 Qt 业务程序目标板上不想装任何 Qt 运行库所以静态交叉编译是唯一合理的选择。1.2 静态编译的真正成本和边界静态编译不是万能的动手之前你得先搞清楚它的代价。第一是 Qt 本身的体积会变大。一个带 GUI 的静态 Qt 程序release 编译出来一般在 10MB 到 40MB 之间具体取决于你启用了多少模块。这还不算 Qt 自带的字体、qml 模块之类的东西。第二是插件必须静态注册。动态编译的时候Qt 的 platform 插件比如 linuxfb、eglfs、xcb是单独的.so文件运行时按需加载。静态编译时这些插件会被编译成.a或者直接编进可执行文件需要你在代码里手动调用Q_IMPORT_PLUGIN或者在.pro文件里用QTPLUGIN指定这一块不处理好程序会报could not load the Qt platform plugin的错误。第三是第三方库的许可证问题。Qt 本身是 LGPL静态链接意味着你不能简单地用动态替换的方式来遵守许可证如果你的应用不开源你就得考虑购买商业许可或者确保你把对象文件提供给用户让他们能重新链接。这个法律问题虽然不属于技术范畴但做产品之前一定要跟团队确认清楚。另一个边界是工具链兼容性。静态编译只是让 Qt 应用不依赖 Qt 的.so但你的可执行文件仍然依赖目标系统的 glibc、libstdc 和内核接口。如果你用高版本 glibc 的工具链去编译放到低版本 glibc 的板子上跑一样会报version GLIBC_2.xx not found。所以交叉编译之前第一件事就是把工具链和 sysroot 跟目标系统对齐。2. 搭建前的基础设施2.1 宿主机、工具链与目标系统的版本匹配我这次用的宿主机是 Ubuntu 20.04 x86_64目标板是 aarch64 架构的 Linux 系统glibc 版本是 2.31跟你自己的目标环境越接近越好。工具链我直接用的 Ubuntu 官方源里的gcc-aarch64-linux-gnu版本是 9.4.0配合 glibc 2.31 的 sysroot 使用。如果你要编译的目标板 glibc 版本更高比如 Ubuntu 22.04 的 glibc 2.35那我建议你在 22.04 的宿主机上装gcc-aarch64-linux-gnu或者直接使用 ARM 官方提供的aarch64-none-linux-gnu工具链。版本匹配是静态编译里最重要的一环它决定你最终程序的兼容性边界。先看一下目标板上系统的信息可以在板子上执行cat /etc/os-release ldd --version uname -a然后在宿主机上确认工具链版本aarch64-linux-gnu-gcc --version如果你的目标板还能联网最简单的办法是用debootstrap生成一个跟目标板相同发行版版本的 rootfs 作为 sysroot。例如要生成 Ubuntu 20.04 的 arm64 rootfssudo debootstrap --archarm64 --variantminbase focal /opt/sysroot/aarch64 http://ports.ubuntu.com/ubuntu-ports/这步会下载一份完整的 arm64 根文件系统里面包含了 arm64 版本的 glibc、libstdc 和一堆基础库。以后交叉编译第三方库的时候装依赖就会方便很多。2.2 sysroot 的制作与目录规划sysroot 是什么简单理解就是目标板的根文件系统在宿主机上的一个副本。交叉编译时GCC 和链接器会到这个目录下去找头文件和库文件而不是到宿主机的/usr/include里找这样编出来的程序在目标板上才能找到正确的运行时依赖。我的目录规划是这样的/opt/ ├── sysroot/ │ └── aarch64/ # arm64 rootfs也就是 sysroot │ ├── usr/ │ ├── lib/ │ └── etc/ ├── qt-src/ │ └── qt-everywhere-src-5.14.2/ # Qt 源码 ├── qt5.14.2-aarch64/ # 目标板运行时的 Qt 安装目录extprefix └── qt5.14.2-aarch64-tools/ # 宿主机上的 Qt 工具目录hostprefix注意 Qt 交叉编译有个概念-prefix是目标板上 Qt 安装的路径-extprefix是 sysroot 之外的备选安装路径-hostprefix是宿主机上放的qmake、moc、uic等工具所在的位置。交叉编译时在宿主机上运行的 Qt 工具比如 moc、uic、rcc必须是用宿主机架构编译出来的否则 x86 的机器跑不了 aarch64 的可执行文件。这点非常容易遗漏后面我会细讲。sysroot 准备好之后一般板子上的/lib和/usr/lib都是符号链接debootstrap 生成时已经处理好不用动。你只需要确认编译器能用它echo int main(){return 0;} test.c aarch64-linux-gnu-gcc --sysroot/opt/sysroot/aarch64 -o test test.c file test如果输出是ELF 64-bit LSB executable, ARM aarch64说明工具链和 sysroot 基本没问题。2.3 环境变量与常用工具交叉编译 Qt 之前我建议先把环境变量整理好。虽然 configure 可以通过参数指定但环境变量能避免很多麻烦export SYSROOT/opt/sysroot/aarch64 export CROSSaarch64-linux-gnu export CC$CROSS-gcc export CXX$CROSS-g export AR$CROSS-ar export RANLIB$CROSS-ranlib export LD$CROSS-ld export PKG_CONFIG_PATH$SYSROOT/usr/lib/aarch64-linux-gnu/pkgconfig:$SYSROOT/usr/share/pkgconfig export PKG_CONFIG_SYSROOT_DIR$SYSROOT export PKG_CONFIG_LIBDIR$SYSROOT/usr/lib/aarch64-linux-gnu/pkgconfigPKG_CONFIG_SYSROOT_DIR和PKG_CONFIG_LIBDIR这两个变量在编译第三方库时非常关键如果不设置pkg-config 会去找宿主机的.pc文件到头来链接的本机库不是你 sysroot 里的 arm64 库会出各种诡异的链接错误。还需要装一些基础工具build-essential、pkg-config、flex、bison、libtool、cmake。Qt 的 configure 脚本在检测依赖时会用这些命令少了哪个它可能就直接关闭某个特性甚至编译到一半报错。3. 依赖库的交叉编译3.1 OpenSSL 静态库编译Qt 的 QtNetwork 模块默认会尝试链接 OpenSSL。如果不启用 openssl 链接Qt5Network 依然能编译但 HTTP 的 HTTPS 请求就会运行时失败。对于要出产品的程序HTTPS 基本上是必须的所以 OpenSSL 还是老老实实编上。我用的版本是 OpenSSL 1.1.1k跟 Qt 5.14.2 完全兼容。下载源码后在源码目录执行./Configure linux-aarch64 \ --prefix$SYSROOT/usr \ --libdirlib/aarch64-linux-gnu \ --cross-compile-prefixaarch64-linux-gnu- \ no-shared \ no-testslinux-aarch64是 OpenSSL 对 aarch64 Linux 的配置目标no-shared表示只生成静态库因为我们要静态链接。配置完成后make -j$(nproc) make install编译完检查一下$SYSROOT/usr/lib/aarch64-linux-gnu/下是否有libcrypto.a和libssl.a这一步就完成了。注意--libdirlib/aarch64-linux-gnu这个参数很容易漏。Ubuntu 的 arm64 系统默认把 64 位库放在这个目录不指定的话 OpenSSL 会装到/usr/lib虽然不影响链接但 pkg-config 搜索路径经常会对不上还是提前统一好。3.2 zlib、libpng、libjpeg 等基础库Qt 的图片插件需要 libpng 和 libjpeg压缩相关的需要 zlib。理论上 Qt configure 可以启用-qt-zlib -qt-libpng -qt-libjpeg让 Qt 自己编译内置版本这是最省事的方式不需要单独交叉编译这些库。但你也搞不清项目后面会不会直接用到这些库的 API我最后还是把 zlib 和 libpng 单独编了一遍放进 sysroot 里。zlib 的交叉编译很简单CCaarch64-linux-gnu-gcc \ ARaarch64-linux-gnu-ar \ RANLIBaarch64-linux-gnu-ranlib \ ./configure --static --prefix$SYSROOT/usr make -j$(nproc) make installlibpng 的交叉编译稍微麻烦点它依赖 zlib需要让它的 Makefile 能发现 zlib 的头文件和库./configure \ --hostaarch64-linux-gnu \ --prefix$SYSROOT/usr \ CCaarch64-linux-gnu-gcc \ CPPFLAGS-I$SYSROOT/usr/include \ LDFLAGS-L$SYSROOT/usr/lib/aarch64-linux-gnu \ --enable-static --disable-shared make -j$(nproc) make install这些库属于比较基础的依赖编译时一般不会出太大问题。真正让我折腾了很久的是显示后端的依赖。3.3 显示后端相关依赖xcb 与 linuxfb/eglfs 的取舍Qt 在 Linux 上显示输出有几种平台插件xcbX11、linuxfbframebuffer、eglfsOpenGL ES DRM/KMS、wayland 等。对于 aarch64 的嵌入式设备你需要根据目标硬件来决定用哪个。如果你的目标板跑的是完整的桌面环境有 X11 服务那就需要 xcb。但 xcb 这套依赖非常重它需要libxcb、xcb-util-*、libxkbcommon、libxkbcommon-x11一堆库而且每库都得到 sysroot 里编一份静态版本。我这次的目标板是纯生产环境没有 X11只有 HDMI 直连的 LCD 屏所以我直接放弃了 xcb用linuxfb平台插件。这样一下省掉了大量工作。Qt configure 的时候加-no-xcb就不会去检测 xcb 依赖加了-linuxfb就会启用 framebuffer 平台插件。如果你的硬件支持 GPU 并且你有对应的 EGL 驱动可以加-eglfs显示效果更好还能实现 Qt Quick 的 OpenGL 加速。没有 GPU 或者驱动不全老老实实linuxfb。注意linuxfb 确实是嵌入式里最稳的方案但它没有硬件加速绘图稍微复杂一点性能就上不去。如果你的应用有频繁的动画或复杂界面建议先确认板子的 GPU 型号和驱动情况再决定要不要上 eglfs。我这次做的是一个偏数据展示的界面linuxfb 足够。如果你的 Qt 版本要开启 eglfs你还需要在 sysroot 里准备libgbm、libudev、libdrm这些库。一般用debootstrap生成的 rootfs 里没有这些开发包可以用qemu-user配合 chroot 进 sysroot 用 apt 装或者直接从目标板上的/usr/lib拷贝到 sysroot 里。这个方案比较灵活但容易混入目标板上没用到的库我还是偏向手动编译。4. Qt5.14.2 的 configure 到 make4.1 configure 参数逐项解析拿到 Qt 源码之后先用qt-everywhere-src-5.14.2.tar.xz解压然后建立一个独立的 build 目录。Qt 官方说支持 out-of-source 构建但 5.14 版本有些模块在 out-of-source 时还是会出问题所以我直接采用了源码目录内编译省事。cd /opt/qt-src/qt-everywhere-src-5.14.2 ./configure \ -prefix /opt/qt5.14.2-aarch64 \ -extprefix /opt/qt5.14.2-aarch64 \ -hostprefix /opt/qt5.14.2-aarch64-tools \ -xplatform linux-aarch64-gnu-g \ -static \ -release \ -opensource \ -confirm-license \ -skip qtwebengine \ -skip qtwebview \ -skip qtwayland \ -nomake examples \ -nomake tests \ -no-xcb \ -linuxfb \ -no-opengl \ -openssl-linked \ -I$SYSROOT/usr/include \ -L$SYSROOT/usr/lib/aarch64-linux-gnu \ -qt-zlib -qt-libpng -qt-libjpeg逐个解释一下这些参数-xplatform linux-aarch64-gnu-g这个最关键。它告诉 Qt 使用qtbase/mkspecs/devices/linux-aarch64-gnu-g这个配置里面已经定义好了 aarch64 编译器、qmake.conf 等不需要自己写 mkspec。-static生成静态库而不是.so。不加这个参数后面全白搭。-release编译 release 版本裁剪调试信息控制体积。-hostprefix宿主机上的 Qt 工具安装目录这个千万不能省。交叉编译的时候bootstrapped 的 qmake、moc、uic 会被安装到这个目录后续编应用要用。-skip qtwebengineQt WebEngine 模块在 aarch64 交叉编译时配置复杂度极高静态编译更是重灾区不用就跳过。-no-xcb配合我们上面讲的目标环境没有 X11。-linuxfb启用 framebuffer 平台插件。-no-opengl如果你确定不用 OpenGL可以直接关掉省去libGL的依赖。如果应用要用 QPainter 之类不影响。-openssl-linked跟 OpenSSL 静态链接需要你在-I和-L里指定好头文件和库路径。配置好之后configure 会跑几十个测试项目。如果输出末尾没有明显的 error就可以进入编译。4.2 编译过程与时间、资源参考make -j$(nproc)。我当时的机器是 8 核 16 线程整个编译过程大约用了 45 分钟到 1 小时。如果你内存小于 8GB建议把-j调低到 4否则内存不够会 OOM现象是编译到一半进程直接被杀死。编译的日志建议重定向到文件make -j$(nproc) 21 | tee /tmp/qt_build.log编译过程中最常见的错误是某模块找不到某个头文件或者链接时报 undefined reference。遇到这种问题不要急着重新配置先看日志里的路径和名字。这一步我也踩了不少坑下面第 6 章会集中说。编译完成后make install安装结束之后/opt/qt5.14.2-aarch64/下面应该是 Qt 的库、头文件、平台插件/opt/qt5.14.2-aarch64-tools/下面应该是可以运行在宿主机上的bin/qmake、moc、uic等工具。4.3 验证 Qt 交叉环境是否可用安装完成之后最好马上做一个冒烟测试确认你的 Qt 环境不是半残的。我一般会写个最简单的窗口程序测#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Hello Qt on aarch64); label.show(); return app.exec(); }编辑.pro文件QT core gui greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET hello TEMPLATE app SOURCES main.cpp然后用 host 端的 qmake 编译/opt/qt5.14.2-aarch64-tools/bin/qmake hello.pro make file hello如果输出是ELF 64-bit LSB executable, ARM aarch64说明基本环境是通的。然后把这个hello拷贝到目标板上执行。如果目标板有 framebuffer就直接./hello -platform linuxfb看到界面上出现文字说明整套链路跑通了。这里要特别注意qmake一定要用-hostprefix里面的那个不要用-prefix里的 qmake。-prefix里的 qmake 是给目标板用的宿主机直接运行会报Exec format error。很多教程写的时候混着用导致编译应用时链接到了错误架构的 Qt 库这一点我后面还会强调。5. 应用工程迁移到静态 Qt 环境5.1 工程文件怎么写你的项目要能在这个静态 Qt 环境下编译.pro文件建议加上这些QT core gui widgets network TARGET myapp TEMPLATE app CONFIG static SOURCES main.cpp mainwindow.cpp # 让 Qt 在 mingw 的 mkspec 下能自动找到平台插件 QTPLUGIN qlinuxfb # 静态链接时把所有需要的 Qt 模块都链进来 LIBS -lssl -lcrypto -ldl -lpthread -lzCONFIG static不是必须的因为你的 Qt 本身就是静态库qmake 会自己处理。但显式加上没坏处能让链接器参数更明确。QTPLUGIN qlinuxfb是新版 Qt 推荐的静态插件注册方式它会在编译时自动把 linuxfb 平台插件链进可执行文件。如果你的代码里用了Q_IMPORT_PLUGIN比如某些自定义插件你需要把它放在main.cpp里#include QtPlugin Q_IMPORT_PLUGIN(QLinuxFbIntegrationPlugin)但用了QTPLUGIN就不用手动写。两种方式二选一别重复。5.2 静态插件注册与平台插件这一节是很多人踩坑的重灾区。Qt 平台插件是动态架构的典型代表。动态编译时platforms/libqlinuxfb.so放在可执行文件旁的platforms/目录下Qt 运行时会去加载。静态编译时插件被直接编进程序里但 Qt 的插件注册机制还是按“按名字查找”的逻辑来跑所以你得告诉链接器“我要用 linuxfb 插件”。如果漏了这一项运行程序时会报qt.qpa.plugin: Could not load the Qt platform plugin linuxfb in even though it was found.注意这句话很骗人看起来像“找到了但加载不了”其实根本原因是插件没有静态注册。加QTPLUGIN qlinuxfb即可。还有一种情况是你跑的程序用了多个平台插件比如支持-platform linuxfb和-platform eglfs那.pro里就写QTPLUGIN qlinuxfb qeglfsQt 会把这些插件对应的目标文件全部链接进来。缺点是可执行文件会变大但换来的是灵活性。5.3 部署目标板的完整文件组织静态编译出来的程序虽然不需要 Qt 库但是有的资源还是得带。拿我这次的程序举例部署到目标板上的文件结构大概是/opt/myapp/ ├── myapp # 静态可执行文件 ├── zh_CN.qm # 翻译文件 ├── config.ini # 程序配置 ├── fonts/ │ └── wqy-microhei.ttc # 中文字体 └── icons/ └── app.pngQt 应用在嵌入式 Linux 上经常遇到中文显示方框的问题。这个跟 Qt 本身无关是系统里没有中文字体或者 Qt 的 fontconfig 依赖没启用。静态编译时如果需要较好的字体匹配Qt 会依赖于 fontconfig 库这意味着你还得在 sysroot 里准备libfontconfig的静态库并且在 configure 时不要加-no-fontconfig。我没有启用 fontconfig而是在代码里直接指定字体文件QFont font(/opt/myapp/fonts/wqy-microhei.ttc); font.setPointSize(12); QApplication::setFont(font);这种方式在 linuxfb 平台下非常可靠也不依赖 fontconfig强烈推荐嵌入式场景直接指定字体路径。翻译文件这块Qt 的QTranslator机制正常用。编译生成.qm文件部署时放到固定路径程序启动时加载QTranslator translator; if (translator.load(/opt/myapp/zh_CN.qm)) { app.installTranslator(translator); }6. 常见问题与排查技巧实录6.1 configure 阶段报错configure 报错有两类一类是依赖缺失一类是交叉编译测试程序无法运行。“The test for linking against libxcb ... failed”这个要么是 xcb 依赖没编要么是你没加-no-xcb。如果你目标平台不用 X11直接加-no-xcb关闭如果要支持 xcb就得把 xcb 全套依赖xcb-util、xcb-image、xcb-keysyms、xkbcommon 等的静态库逐一编进 sysroot。“The test for linking against libGL ... failed”嵌入式板子一般没有完整的 OpenGL 开发库。要么-no-opengl要么明确使用-opengl es2并确保 sysroot 里有libgles2和libegl1的开发包。还有一个比较隐蔽的问题configure 会自动生成一堆小的测试程序并尝试在宿主机上运行。交叉编译时这些测试程序是 aarch64 架构的宿主机不能直接运行所以 Qt 用了一个技巧通过-device-option CROSS_COMPILE...来让测试程序在模拟器或者目标板上运行。但我们用的linux-aarch64-gnu-gmkspec 已经处理了这些正常情况下不会卡死。如果你遇到 configure 卡在某个测试上超过十几分钟去看config.log里面有非常详细的错误原因几乎所有 configure 问题都能在里面找到答案。6.2 编译阶段报错“undefined reference toSSL_new”或者 HTTPS 相关代码编译报错基本都是 OpenSSL 没链接进来。在.pro文件里加LIBS -lssl -lcrypto如果已经加了还是报错检查 OpenSSL 静态库是否真的编译出了libssl.a和libcrypto.a以及 Qt configure 时-I和-L是否指向了 sysroot 的正确路径。“cannot find -lfontconfig”如果 QApplication 或者 QFontDatabase 相关的代码报这类错说明你在 configure 时开了 fontconfig但 sysroot 里没有。要么去编 fontconfig 的静态库要么 configure 时加-no-fontconfig然后在代码里手动指定字体文件。“qmake: could not exec /usr/lib/aarch64-linux-gnu/qt5/bin/qmake”这个错误很典型是 PATH 里混入了系统自带的 Qt 工具导致 make 的时候调用了错误的 qmake。解决办法是重新确认你的 PATH并把/opt/qt5.14.2-aarch64-tools/bin放在最前面export PATH/opt/qt5.14.2-aarch64-tools/bin:$PATH6.3 运行阶段问题程序能启动但界面上全是方块/乱码字体缺失。参照第 5.3 节用QFont加载指定字体文件。程序启动后黑屏或者刷新缓慢linuxfb 平台下性能瓶颈通常在 framebuffer 的绘制方式。Qt 的 linuxfb 插件默认会用 memcpy 把窗口内容拷贝到/dev/fb0如果屏幕分辨率高比如 1920x1080每次局部刷新都会很吃力。可以尝试用-platform linuxfb:fb/dev/fb0来指定 framebuffer 设备同时尽量缩小窗口尺寸或减少不透明窗口部件数量。程序运行时提示This plugin does not support propagateSizeHints()这个是 linuxfb 插件很常见的提示不影响功能只是警告。忽略即可。运行时报libgcc_s.so.1 must be installed for pthread_cancel to work这个错误比较坑它不一定表示真的缺库而是静态编译时 gcc 的 pthread 取消逻辑没有正确处理。解决办法是在.pro里加QMAKE_LFLAGS -Wl,--no-as-needed或者在链接时显式带上-lpthread。这个报错在 aarch64 静态编译里出现的概率很高我查了很多资料才定位到。可执行文件在宿主机上能跑x86交叉编译后丢到板子上报 Exec format error这种情况一般不是文件本身的问题而是你没有用交叉编译的 Qt。检查file 你的程序如果显示x86-64说明你的 qmake 用错了用了宿主机上系统自带的 Qt 的 qmake而不是/opt/qt5.14.2-aarch64-tools/bin/qmake。6.4 做完整套环境之后我沉淀下来的几个习惯第一个习惯是每次重编 Qt 之前把 configure 参数原封不动存到一个 shell 脚本里命名带日期注释写明用途。这套环境一旦编译好短期内不太会动但是过了几个月再回来看可能已经完全忘了当时为什么加某些参数。有脚本在重装环境就是一条命令的事不用费劲回忆。第二个习惯是始终保留一份编译日志。Qt 这种大工程的编译问题很多是在一百多屏日志之后才出现细微的错误。没有日志出错之后只能重新编译一遍浪费时间。有日志之后直接grep -i error /tmp/qt_build.log几秒钟就能定位。第三个习惯是我在实际操作中体会最深的一点不要追求“一次配置永久使用”。不同项目对 Qt 模块的需求不一样有的要 WebEngine有的要 OpenGL有的要 xcb有的不要。我后来根据项目需求维护了两套 Qt aarch64 环境一套精简版linuxfb无 OpenGL无网络模块的依赖一套完整版带 network、sql、qml 等常用模块。这样不同项目直接用对应的环境编译不用每次重新 configure。最后静态交叉编译这个事第一次做确实会觉得很繁琐但当你看到目标板上只有一个孤零零的可执行文件双击就能跑起来再也不用担心缺库、版本冲突、部署环节出错的时候之前的折腾都值了。希望这份手册能帮你少踩几个坑。