【Linux 服务器环境搭建】从零到端到端：OpenCloudOS 9 构建鸿蒙 PC Qt 交叉编译服务器

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

本文以一台全新 Linux 云服务器（OpenCloudOS 9.4 / 腾讯云 / 8 核 15 GB）为起点，从 SSH 第一次登录 到完整搭建出一台可用于鸿蒙 PC Qt 交叉编译的"生产级 Linux 构建服务器"，全部命令、输出、踩坑、修复都来自真实终端，无任何编造。

---

项目信息说明

项目	内容
本文主题	Linux 服务器环境搭建——把一台全新 Linux 云主机改造成"鸿蒙 PC Qt 应用构建服务器"
服务器供应商	腾讯云（CVM）
服务器配置	8 核 / 15 GB RAM / 200 GB 磁盘 / 2.5 GB/s 上行带宽
操作系统	OpenCloudOS Server 9.4（与 RHEL 9 / Rocky 9 二进制兼容）
登录方式	SSH 22 / root + 密码（生产环境建议改密钥）
包管理	yum / dnf（OpenCloudOS 与 CentOS Stream 9 同源）
关键服务角色	编译宿主机（host = x86_64）→ 交叉编译 → 目标机（target = aarch64 鸿蒙 PC）
依赖软件	yum 系统包（cmake / ninja / patchelf / Qt5）+ 外部下载（OHOS SDK + Qt-OHOS）
磁盘占用	总 4 GB（OHOS SDK 2.8 G + Qt-OHOS 622 M + 系统包 500 M）
耗时	约 30 分钟（含外部下载 ≈ 8 分钟、本地解压配置 ≈ 22 分钟）
验收方式	5 项基线检查 + Hello-World 端到端编译 + ELF 5 项产物体检
真坑数	2 个（CMAKE_PREFIX_PATH 在交叉工具链下失效 + 第三方 SDK 自带 Windows host 工具）

这篇文章会回答的问题

• 拿到一台全新 Linux 云服务器，第一件事该做什么？基线怎么定？
• yum / dnf 系交叉编译服务器必装系统包清单是什么？为什么？
• 外部下载源（华为云镜像 / gitcode）怎么选？带宽和稳定性如何？
• 服务器侧 ~/.bashrc 永久化的最佳实践？环境变量怎么不污染、不冲突？
• 自定义 SDK / 闭源 SDK 进 Linux 服务器后典型踩坑怎么处理？
• Linux 服务器搭好之后，怎么用Hello-World 端到端验证生产可用？

---

〇、整体方案：从全新 Linux 主机到生产可用构建机

整套链路 30 分钟内 跑完。下面按真实操作顺序展开。

---

一、起点：刚拿到一台 Linux 云主机的样子

任何 Linux 服务器搭建工作的第一步都不是"装东西"，而是定基线——硬件配置、OS 版本、已有命令、关键环境变量。明确了"我从哪里开始"，后续每一步增量才能讲清楚。

本次拿到的服务器基线一目了然：

• 硬件层：8 核 CPU、15 GiB 内存、200 GB 磁盘（仅 7% 已用、188 GB 可用）
• 系统层：OpenCloudOS Server 9.4（内核 6.6.69）——RHEL/Rocky 9 系，dnf + yum 双包管理器都可用
• 已有命令：系统默认带 gcc / clang / make / python3 / wget / tar / git（开发常用工具齐全）
• 缺失工具：cmake / ninja / patchelf / Qt5 系全部空白
• 环境变量：OHOS_SDK_ROOT / QT_OHOS_ROOT 都为空（说明这台机器之前没做过任何鸿蒙相关工作）

这是一个纯净起点——后续每一步增量都有真实意义。

---

二、第一步：yum 装齐构建工具链系统包

Linux 服务器搭建工作里最容易被低估的环节就是"装系统包"——很多人觉得没什么含金量，但事实是：这一步选错版本、漏装关键包、或者忽略源问题，后面会反复返工。

OpenCloudOS 9 的官方 yum 仓库已经覆盖了鸿蒙 PC + Qt 交叉编译所需的全部基础工具，一条命令搞定：

yum install -y cmake ninja-build patchelf \
    qt5-qtbase-devel qt5-qttools-devel qt5-qtsvg-devel qt5-qtxmlpatterns-devel \
    rsync sshpass bzip2 unzip xz which

为什么需要这些包？

包	作用
cmake 3.26.5	现代构建系统（鸿蒙 PC 上业务编 SHARED 库需要它）
ninja-build 1.11.1	高速构建工具，配合 cmake -G Ninja 使用
patchelf	修改 ELF 文件的 SONAME / RPATH / NEEDED，处理 .so 部署兼容性
qt5-qtbase-devel	提供系统的 host Qt5 工具：moc-qt5 / rcc-qt5 / uic-qt5 / qmake-qt5
qt5-qttools-devel	提供 lrelease-qt5（翻译文件编译）
rsync / sshpass	服务器和 Mac 之间同步源码、产物

⚠️ 关键观察：系统 Qt 是 5.15.11，而目标 Qt-OHOS 是 5.12.12 —— 这个版本错配将在后面的 moc ABI 上引出连锁反应。

---

三、外部下载 #1：从华为云镜像拉 OHOS SDK

OpenHarmony 5.0.1-Release 的 SDK 在华为云镜像上：

cd /root
wget -q --show-progress "https://repo.huaweicloud.com/openharmony/os/5.0.1-Release/ohos-sdk-windows_linux-public.tar.gz"
# 2.5 GB · 实测 3 分 19 秒 · 26 MB/s 直连

校验 sha256（必须做）

wget -q "https://repo.huaweicloud.com/openharmony/os/5.0.1-Release/ohos-sdk-windows_linux-public.tar.gz.sha256"
sha256sum ohos-sdk-windows_linux-public.tar.gz
# 期望：575a245258270b7847bc9ea7045757e6430c61143e0958bfe2da89c7c8de9bf1
# 实际：575a245258270b7847bc9ea7045757e6430c61143e0958bfe2da89c7c8de9bf1 ✓

解压（两层结构）

OHOS SDK 是个嵌套包——外层 .tar.gz 包含 5 个 .zip（按角色分类）：

mkdir -p ohos-sdk-extracted
tar xzf ohos-sdk-windows_linux-public.tar.gz -C ohos-sdk-extracted/
ls ohos-sdk-extracted/linux/
# ets-linux-x64-5.0.1.111-Release.zip          (84M)     ArkTS 编译器
# js-linux-x64-5.0.1.111-Release.zip           (56M)     JS 工具链
# native-linux-x64-5.0.1.111-Release.zip       (869M)    ← 我们需要的
# previewer-linux-x64-5.0.1.111-Release.zip    (171M)    UI 预览器
# toolchains-linux-x64-5.0.1.111-Release.zip   (22M)     Hap 打包工具

对 C++ 交叉编译来说，只需要 native 这一个 zip：

mkdir -p /root/ohos-sdk/12
unzip -q native-linux-x64-5.0.1.111-Release.zip -d /root/ohos-sdk/12/
ls /root/ohos-sdk/12/native/
# build/  build-tools/  llvm/  sysroot/  docs/
# compatible_config.json  nativeapi_syscap_config.json  ndk_system_capability.json  NOTICE.txt

验证关键文件

# 1. CMake toolchain 文件
ls /root/ohos-sdk/12/native/build/cmake/ohos.toolchain.cmake
# ← 后面 cmake configure 时要传给 -DCMAKE_TOOLCHAIN_FILE

# 2. OHOS Clang 交叉编译器
/root/ohos-sdk/12/native/llvm/bin/clang++ --version
# OHOS (dev) clang version 15.0.4 (llvm-project ef33c3575763937746833063de4d2e1fd184bbf7)
# Target: x86_64-unknown-linux-gnu
# Thread model: posix

清理掉源 tar.gz 和中间 zip 节省磁盘（约 2.5 + 1.2 GB）：

rm -f /root/ohos-sdk-windows_linux-public.tar.gz
rm -rf /root/ohos-sdk-extracted
df -h /
# /dev/vda1       200G   17G  184G   9% /

---

四、外部下载 #2：从 gitcode 拉 Qt for HarmonyOS（git + lfs）

Qt 官方 wiki (Qt5.12.12_Open_Source_Release_for_HarmonyOS_zh) 只提供源码包 —— 自己编译要几个小时。

捷径：OpenHarmony PC 开发者社区在 gitcode 上托管了预编译版本：

yum install -y git-lfs && git lfs install

mkdir -p /opt/qt-ohos && cd /opt/qt-ohos
time git clone https://gitcode.com/OpenHarmonyPCDeveloper/ohos_Qt5.12.12.git .
# Filtering content: 100% (2/2), 517.18 MiB | 26.16 MiB/s, done.
# real    0m20.692s

20 秒拉完 517 MB（git lfs 自动处理大文件）。仓库结构：

/opt/qt-ohos/
├── docs/                                     # 文档
├── qt_ohos_release/
│   └── qt-5.12.12-ohos_release_20260420.zip  # 171M 预编译 zip
├── qt_ohos_src/                              # 源码（备用）
├── qt_ohos_template/                         # HAP 模板
├── LICENSE
└── README.md

解压预编译版本

mkdir -p qt-5.12.12-ohos
unzip -q qt_ohos_release/qt-5.12.12-ohos_release_*.zip -d qt-5.12.12-ohos/
# real    0m3.533s

ls qt-5.12.12-ohos/qt-5.12.12-ohos/
# bin  doc  include  lib  mkspecs  plugins  qml

验证关键文件

# 1. CMake config（业务工程 find_package(Qt5) 的目标）
find /opt/qt-ohos -name Qt5Config.cmake
# /opt/qt-ohos/qt-5.12.12-ohos/qt-5.12.12-ohos/lib/cmake/Qt5/Qt5Config.cmake ✓

# 2. Qt5 核心库
ls -lh /opt/qt-ohos/qt-5.12.12-ohos/qt-5.12.12-ohos/lib/libQt5Core.so
# -rw-r--r-- 1 root root  34M ✓

# 3. QPA 平台插件（鸿蒙 PC 上 Qt 启动的关键）
ls -lh /opt/qt-ohos/qt-5.12.12-ohos/qt-5.12.12-ohos/plugins/platforms/libqohos.so
# -rw-r--r-- 1 root root 149M ✓

总大小 622 MB。清理 zip 后磁盘累计 18 GB（9%）。

---

五、Linux 服务器侧 ~/.bashrc 永久化：环境变量 + PATH

cat >> ~/.bashrc << "BASHRC_EOF"

# === 鸿蒙 PC + Qt 交叉编译环境 ===
export OHOS_SDK_ROOT=/root/ohos-sdk/12
export QT_OHOS_ROOT=/opt/qt-ohos/qt-5.12.12-ohos/qt-5.12.12-ohos
export PATH=$OHOS_SDK_ROOT/native/llvm/bin:$PATH
BASHRC_EOF

source ~/.bashrc

5 项基线检查（必做）

for x in \
    "$OHOS_SDK_ROOT/native/build/cmake/ohos.toolchain.cmake" \
    "$OHOS_SDK_ROOT/native/llvm/bin/aarch64-unknown-linux-ohos-clang++" \
    "$QT_OHOS_ROOT/lib/cmake/Qt5/Qt5Config.cmake" \
    "$QT_OHOS_ROOT/lib/libQt5Core.so" \
    "$QT_OHOS_ROOT/plugins/platforms/libqohos.so"; do
    [ -e "$x" ] && echo "  ✓ $x" || echo "  ✗ MISSING: $x"
done

5 个 ✓ 全过即代表环境就绪，可以进入 Hello-World 验证。

aarch64-unknown-linux-ohos-clang++ --version | head -3
# OHOS (dev) clang version 15.0.4 ...
# Target: aarch64-unknown-linux-ohos    ← 关键！目标架构必须是这个

---

六、Linux 服务器侧典型踩坑：交叉编译工具链对接

环境配置看起来完成了，但第一次跑构建 cmake configure 的时候，会连续撞上两个 Linux 服务器搭建工程里的典型坑 ——这两个坑都是本系列前序文档里反复强调过的，但只有亲手再踩一遍才能真正理解工具链的细节。

6.1 准备最小 Hello-World

mkdir -p /root/hello-qt-ohos/{src,build-ohos}
cd /root/hello-qt-ohos

src/main.cpp：

#include <QApplication>
#include <QLabel>
int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    QLabel label("Hello, HarmonyOS PC + Qt 5.12.12!");
    label.setStyleSheet("font-size: 24px; color: #FF6B5A; padding: 40px;");
    label.show();
    return app.exec();
}

CMakeLists.txt：

cmake_minimum_required(VERSION 3.16)
project(hello_qt_ohos CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
find_package(Qt5 REQUIRED COMPONENTS Core Gui Widgets)

# ⭐ 注意：鸿蒙 PC 上业务必须编成 SHARED 库，不是 executable
add_library(hello_qt_ohos SHARED src/main.cpp)
target_link_libraries(hello_qt_ohos PRIVATE Qt5::Core Qt5::Gui Qt5::Widgets)

6.2 坑 #1：CMAKE_PREFIX_PATH 失效

第一次跑：

cd build-ohos
cmake -G Ninja \
    -DCMAKE_TOOLCHAIN_FILE=$OHOS_SDK_ROOT/native/build/cmake/ohos.toolchain.cmake \
    -DOHOS_ARCH=arm64-v8a \
    -DCMAKE_PREFIX_PATH=$QT_OHOS_ROOT \
    ..

实际报错：

CMake Error: Could not find a package configuration file provided by "Qt5"
  Add the installation prefix of "Qt5" to CMAKE_PREFIX_PATH or set "Qt5_DIR"

原因：ohos.toolchain.cmake 设置了 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ONLY，让 find_package 只在 sysroot 里找——而 sysroot 里没有 Qt5。命令行传的 CMAKE_PREFIX_PATH 被忽略。

修复：用 Qt5_DIR 精确指定，并改 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE=BOTH 让 find_package 跳出 sysroot：

cmake -G Ninja \
    -DCMAKE_TOOLCHAIN_FILE=$OHOS_SDK_ROOT/native/build/cmake/ohos.toolchain.cmake \
    -DOHOS_ARCH=arm64-v8a \
    -DQt5_DIR=$QT_OHOS_ROOT/lib/cmake/Qt5 \
    -DCMAKE_FIND_ROOT_PATH=$QT_OHOS_ROOT \
    -DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=BOTH \
    ..

6.3 坑 #2：moc.exe 跑不了

修复 #1 后，cmake 走得更远了，但又撞到下一个错：

CMake Error: AUTOMOC for target hello_qt_ohos:
  Test run of "moc" executable "/opt/qt-ohos/qt-5.12.12-ohos/.../bin/moc.exe" failed.
  /opt/qt-ohos/.../bin/moc.exe -h
  Permission denied

根因：看一下 Qt-OHOS 的 bin 目录：

ls /opt/qt-ohos/qt-5.12.12-ohos/qt-5.12.12-ohos/bin/
# moc.exe          823 KB
# rcc.exe          824 KB
# qmake.exe       4.0 MB
# qmlcachegen.exe  1.3 MB
# qvkgen.exe       619 KB
# ...

这些都是 Windows .exe！Linux 上自然跑不了。Qt-OHOS 5.12.12 的官方分发包 host 工具只为 Windows 准备。

修复：用系统的 Qt5 host 工具（5.15.11）软链覆盖 Qt-OHOS bin 下的同名 .exe：

QT_BIN=$QT_OHOS_ROOT/bin
for t in moc rcc uic lrelease qmake; do
    mv $QT_BIN/${t}.exe $QT_BIN/${t}.exe.bak 2>/dev/null
    ln -sf /usr/bin/${t}-qt5 $QT_BIN/${t}.exe
done

# 验证
$QT_BIN/moc.exe --version
# moc.exe 5.15.11 ✓

⚠️ 关于 host 5.15 vs target 5.12 的 ABI 错位：用 5.15 的 moc 给 5.12 头文件生成 metadata，在简单 Q_OBJECT 上没问题，复杂场景（如 LiteIDE / qjackctl）会触发 “SuperData not found” 错误。本仓库有专门的 fix_moc_metaobjects.sh 脚本批量降级，详见 qjackctl 那篇文章。

---

七、Linux 服务器端到端验证：Hello-World 真实跑通

服务器搭好后必须做一次端到端跑通——两个坑修完，第三次 cmake 一气呵成：

cd build-ohos && rm -rf *
cmake -G Ninja \
    -DCMAKE_TOOLCHAIN_FILE=$OHOS_SDK_ROOT/native/build/cmake/ohos.toolchain.cmake \
    -DOHOS_ARCH=arm64-v8a \
    -DQt5_DIR=$QT_OHOS_ROOT/lib/cmake/Qt5 \
    -DCMAKE_FIND_ROOT_PATH=$QT_OHOS_ROOT \
    -DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=BOTH \
    ..

# -- Configuring done (0.1s)
# -- Generating done (0.0s)

ninja
# [1/4] Automatic MOC for target hello_qt_ohos
# [2/4] Building CXX object .../mocs_compilation.cpp.o
# [3/4] Building CXX object .../src/main.cpp.o
# [4/4] Linking CXX shared library libhello_qt_ohos.so   ✓

产物 5 项体检（每次都必须做）

SO=libhello_qt_ohos.so
LLVM=$OHOS_SDK_ROOT/native/llvm/bin

# [1] 文件类型 → 必须 ARM aarch64
file $SO
# libhello_qt_ohos.so: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV)...

# [2] ELF 头 → ELF64 / DYN / AArch64
$LLVM/llvm-readelf -h $SO | grep -E 'Class|Machine|Type'
#   Class:    ELF64
#   Type:     DYN (Shared object file)
#   Machine:  AArch64

# [3] T main 必须导出（Qt-OHOS dlopen 后 dlsym("main")）
$LLVM/llvm-nm -D $SO | grep ' main$'
# 0000000000005f9c T main

# [4] NEEDED 依赖 → 不能有绝对路径
$LLVM/llvm-readelf -d $SO | grep NEEDED
# 0x...  (NEEDED)  Shared library: [libQt5Widgets.so]
# 0x...  (NEEDED)  Shared library: [libQt5Gui.so]
# 0x...  (NEEDED)  Shared library: [libQt5Core.so]
# 0x...  (NEEDED)  Shared library: [libc++_shared.so]
# 0x...  (NEEDED)  Shared library: [libc.so]

# [5] LOAD 段对齐 → 必须是 0x1000（4KB）
$LLVM/llvm-readelf -l $SO | grep ' LOAD '
#   LOAD  0x000000 ... R    0x1000   ← 全部 0x1000
#   LOAD  0x004e6c ... R E  0x1000
#   LOAD  0x00bb80 ... RW   0x1000
#   LOAD  0x00bfc0 ... RW   0x1000

5 项体检全部通过 ✅ —— 业务库已就绪，可以塞进 HAP 模板部署到鸿蒙 PC 真机。

---

八、Linux 服务器最终交付清单

路径	内容	大小
/root/ohos-sdk/12/native/	OHOS Native SDK（toolchain + clang + sysroot）	2.8 GB
/opt/qt-ohos/qt-5.12.12-ohos/qt-5.12.12-ohos/	Qt for HarmonyOS 5.12.12 预编译版	622 MB
/usr/bin/{moc,rcc,uic,lrelease,qmake}-qt5	系统 Qt 5.15.11 host 工具	~10 MB
/usr/bin/{cmake,ninja,patchelf}	现代构建工具	~50 MB

核心环境变量（已永久写入 ~/.bashrc）：

export OHOS_SDK_ROOT=/root/ohos-sdk/12
export QT_OHOS_ROOT=/opt/qt-ohos/qt-5.12.12-ohos/qt-5.12.12-ohos
export PATH=$OHOS_SDK_ROOT/native/llvm/bin:$PATH

Qt-OHOS bin/ 软链（一次性 patch，永久生效）：

/opt/qt-ohos/.../bin/moc.exe       → /usr/bin/moc-qt5
/opt/qt-ohos/.../bin/rcc.exe       → /usr/bin/rcc-qt5
/opt/qt-ohos/.../bin/uic.exe       → /usr/bin/uic-qt5
/opt/qt-ohos/.../bin/lrelease.exe  → /usr/bin/lrelease-qt5
/opt/qt-ohos/.../bin/qmake.exe     → /usr/bin/qmake-qt5

---

九、FAQ

Q1：为什么要装 qt5-qtbase-devel？我不是有 Qt-OHOS 了吗？

A：Qt-OHOS 提供的是 target 端的库（aarch64 的 .so，给业务链接用）；qt5-qtbase-devel 提供的是 host 端的工具（x86_64 的 moc/rcc/uic，构建期生成 metadata 代码用）。两个角色完全不同——前者面向运行时，后者面向编译时。

Qt-OHOS 5.12 官方 bin/ 目录里那些 moc.exe / rcc.exe 是 Windows 二进制，Linux 跑不了。所以 Linux 服务器上必须有一套 host Qt 工具，最简单的方法就是 yum 装系统 Qt5。

Q2：为什么 CMAKE_PREFIX_PATH=$QT_OHOS_ROOT 不起作用？

A：因为 ohos.toolchain.cmake 内部设置了：

set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)  # 限制 find_package 只在 sysroot 找

这是交叉编译的标准做法（防止误链 host 库到 target）。但它会让命令行的 CMAKE_PREFIX_PATH 失效。两种修复方式：

1. 显式 Qt5_DIR（推荐）：直接告诉 cmake Qt5Config.cmake 在哪
2. 改 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE=BOTH + 加 CMAKE_FIND_ROOT_PATH：允许跳出 sysroot 找

本文最终用的是两条都加的稳妥方案——双保险。

Q3：Qt-OHOS host 工具是 .exe 的根因是什么？以后会改吗？

A：根因是华为 Qt-OHOS 团队的 CI 跑在 Windows 上，发布的二进制只覆盖了 Windows host 用例。Linux 用户需要自己想办法。

未来怎么变：

• 长期看 Qt 6.x 上的 OpenHarmony 适配会重视 Linux host
• 短期解决方案就是本文这种软链覆盖——干净、可逆、零环境污染
• 不要尝试在 Wine 里跑 .exe，性能差且不稳定

Q4：sha256 校验为什么这么重要？

A：OHOS SDK 是 2.5 GB 的大文件，下载过程中网络抖动很可能造成几字节差异——这种损坏在解压时不一定报错，但会导致编译时随机奇怪错误（比如某个 .a 文件损坏，链接时报某个具体符号找不到）。

每次下载完 SDK 都做一次 sha256sum 校验是必做的工程动作，能省你 1-2 小时排错时间。

Q5：30 分钟搭完环境太快了？跟仓库前序记录的 2-3 小时不一致？

A：仓库前序记录的 2-3 小时主要消耗在两个地方：

1. 第一次跑这条链路：要查华为云镜像源的位置、Qt-OHOS 仓库在哪、SDK 内部结构、踩坑、找资料——大头都是认知成本
2. 手编 Qt-OHOS 源码：早期没有 gitcode 上的预编译版本，需要自己 configure + make Qt 5.12.12（4 小时起步）

本文做了三件事让总时长压到 30 分钟：

• ✅ 用预编译 Qt-OHOS（gitcode 上的 release zip，171 MB 解压 3.5 秒）
• ✅ 用华为云国内镜像（OHOS SDK 26 MB/s 直连）
• ✅ 把所有踩坑路径事先知道（基于仓库前序经验，本文 6.2/6.3 那两个坑都不用现场摸索）

---

十、总结：Linux 服务器搭建的可复用方法论

本文从一台全新 OpenCloudOS 9.4 云主机起步，30 分钟改造为一台生产可用的"鸿蒙 PC Qt 应用构建服务器"，端到端编出第一个 libhello_qt_ohos.so，5 项产物体检全过。

回看整套操作，可以提炼出一套普适的 Linux 服务器搭建方法论：

1. 先定基线，再装东西——SSH 登录第一件事是"诊断"，不是"动手"
2. 系统包尽量用 yum / dnf，不要自己编——OpenCloudOS / Ubuntu / Debian 的官方源通常够用
3. 外部 SDK 优先选国内镜像（华为云 / gitcode），下载速度差 10x
4. 下载完必做 sha256 校验——2.5 GB 文件网络损坏的概率不低
5. 环境变量永久化到 ~/.bashrc，不要每次 export 一遍
6. 第三方 SDK 自带的 host 工具如果是别的 OS（如 Windows .exe），用软链覆盖最干净
7. 搭好后必须跑一次端到端验证（Hello-World），不要等业务出问题才发现工具链链路不通

关键路径总结：

yum 装包 (cmake/ninja/patchelf + Qt5 host)         5 min
↓
wget OHOS SDK 2.5 GB + 校验 + 解压 native           5 min
↓
git clone Qt-OHOS（含 lfs 517 MB）+ unzip          5 min
↓
~/.bashrc 永久化环境变量                            1 min
↓
软链系统 Qt5 工具覆盖 Qt-OHOS .exe                  1 min
↓
Hello-World CMake + ninja + 5 项体检                3 min

两个必踩坑：

1. CMAKE_PREFIX_PATH 被 toolchain 重置 → 用 Qt5_DIR 精确指定 + FIND_ROOT_PATH_MODE_PACKAGE=BOTH
2. Qt-OHOS bin/ 是 Windows .exe → 软链系统 Qt5 工具覆盖