---

系列导读：上一篇我们搞清楚了 RK3588S 的硬件架构，知道了 NPU 三核结构和内存带宽的重要性。这一篇解决"能跑起来"的问题——把开发环境从零搭好，让你在 PC 上写代码、编译、一键推送到板子运行，调试效率提升 10 倍。

---

一、开发模式选择：本机编译 vs 交叉编译

拿到 RK3588S 开发板后，第一个问题：在哪里写代码、在哪里编译？

有两种模式：

模式	做法	优点	缺点
本机编译	直接在板子上装 GCC 编译	简单，无需工具链	编译慢（A76 比 x86 慢 3-5 倍）、板子存储小
交叉编译	PC 上编译，生成 ARM 二进制，推到板子运行	编译快、调试体验好	需要配置工具链

结论：做 AI 推理开发必须用交叉编译。 RKNN 的 C++ 推理程序编译一次需要几十秒，用板子本机编译会严重拖慢开发节奏。本文全程使用交叉编译方案。

---

二、宿主机环境准备

推荐使用 Ubuntu 22.04 LTS x86_64 作为开发主机，VMware 虚拟机或物理机均可。

注意：如果你用的是 Windows + WSL2，大部分步骤相同，但 USB 串口调试需要额外配置 usbipd-win，建议直接用虚拟机或双系统。

2.1 安装基础依赖

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
    git wget curl vim \
    build-essential cmake ninja-build \
    python3 python3-pip python3-venv \
    libssl-dev libusb-1.0-0-dev \
    pkg-config rsync \
    adb fastboot \
    net-tools openssh-client

2.2 配置 Python 环境（RKNN-Toolkit2 需要）

# 创建专用虚拟环境，避免污染系统 Python
python3 -m venv ~/rknn-env
source ~/rknn-env/bin/activate

# 验证版本（RKNN-Toolkit2 要求 Python 3.8-3.11）
python3 --version

⚠️ 常见踩坑：RKNN-Toolkit2 对 Python 版本敏感，Ubuntu 22.04 默认的 Python 3.10 是兼容的，但如果你额外安装了 Python 3.12，务必在虚拟环境中指定版本，否则安装 rknn-toolkit2 时会报依赖错误。

---

三、交叉编译工具链安装

3.1 下载官方工具链

瑞芯微官方推荐使用 Linaro 提供的 aarch64-linux-gnu 工具链：

# 创建工具链目录
mkdir -p ~/toolchain && cd ~/toolchain

# 下载 gcc-arm-10.3（与 RK 官方 SDK 版本匹配）
wget https://developer.arm.com/-/media/Files/downloads/gnu-a/10.3-2021.07/binrel/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu.tar.xz

# 解压
tar -xf gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu.tar.xz

3.2 配置环境变量

# 写入 ~/.bashrc，永久生效
echo 'export CROSS_COMPILE_PATH=~/toolchain/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu' >> ~/.bashrc
echo 'export PATH=$CROSS_COMPILE_PATH/bin:$PATH' >> ~/.bashrc
echo 'export CROSS_COMPILE=aarch64-none-linux-gnu-' >> ~/.bashrc
echo 'export ARCH=arm64' >> ~/.bashrc

source ~/.bashrc

3.3 验证安装

aarch64-none-linux-gnu-gcc --version
# 期望输出：aarch64-none-linux-gnu-gcc (GNU Toolchain ...) 10.3.1

3.4 写一个 Hello World 验证交叉编译

// test_cross.c
#include <stdio.h>
int main() {
    printf("Hello from RK3588S!\n");
    return 0;
}

# 交叉编译
aarch64-none-linux-gnu-gcc -o test_cross test_cross.c

# 查看文件类型（必须是 aarch64）
file test_cross
# 输出：test_cross: ELF 64-bit LSB executable, ARM aarch64, ...

# 推到板子运行
adb push test_cross /tmp/
adb shell chmod +x /tmp/test_cross
adb shell /tmp/test_cross
# 输出：Hello from RK3588S!

---

四、RKNN SDK 安装与目录结构解析

4.1 获取 RKNN-Toolkit2

# 从官方 GitHub 克隆（建议克隆完整仓库，包含示例）
git clone https://github.com/airockchip/rknn-toolkit2.git ~/rknn-toolkit2
cd ~/rknn-toolkit2

💡 提示：如果 GitHub 速度慢，可以用 Gitee 镜像：

git clone https://gitee.com/mirrors/rknn-toolkit2.git ~/rknn-toolkit2

4.2 安装 Python 包

source ~/rknn-env/bin/activate
cd ~/rknn-toolkit2/rknn-toolkit2/packages

# 选择对应 Python 版本的 whl
# Python 3.10 用这个：
pip install rknn_toolkit2-2.x.x-cp310-cp310-linux_x86_64.whl

# 验证安装
python3 -c "from rknn.api import RKNN; print('RKNN-Toolkit2 OK')"

4.3 SDK 目录结构解析

安装完成后，整个 SDK 的关键目录如下：

rknn-toolkit2/
├── rknn-toolkit2/              # PC 端 Python 工具（模型转换、精度分析）
│   ├── packages/               # whl 安装包
│   └── examples/               # 官方转换示例（强烈建议通读）
│
├── rknn_model_zoo/             # 官方模型库（YOLOv8/ResNet/MobileNet 等预转换模型）
│   ├── models/
│   └── examples/
│
└── rknpu2/                     # 板端 C/C++ 推理库
    ├── runtime/
    │   └── Linux/
    │       └── librknn_api/
    │           ├── aarch64/
    │           │   ├── librknnrt.so    ← 板端核心运行时库
    │           │   └── rknn_server     ← 调试用服务端
    │           └── include/
    │               └── rknn_api.h      ← C API 头文件
    └── examples/               # C++ 推理示例

⚠️ 关键文件说明：

• librknnrt.so：板端推理运行时，编译 C++ 程序时需要链接，部署时需要推到板子的 /usr/lib/
• rknn_api.h：所有推理 API 的入口，后续系列会深度讲解
• rknn_server：PC 模拟推理时使用的服务端，调试阶段非常有用

---

五、板子系统配置

5.1 通过 ADB 连接板子

# 确认 ADB 能识别板子
adb devices
# 输出：List of devices attached
#        xxxxxxxx    device

# 进入 shell
adb shell

5.2 推送运行时库到板子

# 将 librknnrt.so 推到板子系统库目录
adb push ~/rknn-toolkit2/rknpu2/runtime/Linux/librknn_api/aarch64/librknnrt.so /usr/lib/

# 更新动态库缓存
adb shell ldconfig

# 验证库版本
adb shell "strings /usr/lib/librknnrt.so | grep -i 'librknnrt version'"

5.3 配置 SSH（告别 ADB，用网络传文件）

长期开发用 SSH 比 ADB 方便得多，支持 VSCode 远程连接：

# 板子上安装 SSH 服务（如果没有）
adb shell "apt install openssh-server -y"
adb shell "systemctl enable ssh && systemctl start ssh"

# 查看板子 IP
adb shell "ip addr show eth0 | grep 'inet '"

# PC 上测试连接（默认用户名通常是 root 或 linaro）
ssh root@192.168.x.x

---

六、VSCode 远程开发配置

这是整个开发环境中效率提升最大的一步。配置完成后，你可以直接在 VSCode 里编辑板子上的文件、运行终端、调试程序，体验与本地开发完全一致。

6.1 安装 Remote-SSH 插件

在 VSCode 扩展商店搜索安装：

• Remote - SSH（Microsoft 官方）
• C/C++（IntelliSense 支持）
• CMake Tools

6.2 配置 SSH 免密登录

# PC 上生成密钥（如果还没有）
ssh-keygen -t ed25519 -C "rk3588s-dev"

# 推送公钥到板子
ssh-copy-id root@192.168.x.x

# 测试免密登录
ssh root@192.168.x.x  # 不需要输密码即为成功

6.3 配置 VSCode SSH 连接

按 Ctrl+Shift+P → 输入 Remote-SSH: Open SSH Configuration File，在配置文件中添加：

Host rk3588s
    HostName 192.168.x.x
    User root
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 30

之后按 Ctrl+Shift+P → Remote-SSH: Connect to Host → 选择 rk3588s，即可直接在 VSCode 中打开板子上的目录。

6.4 配置交叉编译 CMake 工程

在项目根目录创建 CMakeLists.txt：

cmake_minimum_required(VERSION 3.16)
project(rknn_demo)

set(CMAKE_C_COMPILER aarch64-none-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-none-linux-gnu-g++)

set(RKNN_SDK_PATH "$ENV{HOME}/rknn-toolkit2/rknpu2/runtime/Linux/librknn_api")

add_executable(rknn_demo main.cpp)

target_include_directories(rknn_demo PRIVATE
    ${RKNN_SDK_PATH}/include
)

target_link_directories(rknn_demo PRIVATE
    ${RKNN_SDK_PATH}/aarch64
)

target_link_libraries(rknn_demo
    rknnrt
    pthread
    dl
)

编译并部署：

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

# 一键推到板子
adb push rknn_demo /tmp/ && adb shell chmod +x /tmp/rknn_demo

💡 推荐做法：把上面的 adb push 命令写成 deploy.sh 脚本，在 VSCode 的 tasks.json 里配置为构建后任务，实现"保存代码→编译→推板→运行"一键完成。

---

七、常见踩坑汇总

这里整理了初次搭建环境时最容易遇到的问题：

问题	原因	解决方案
rknn_toolkit2 安装报依赖冲突	Python 版本不匹配	严格使用 Python 3.8-3.11，建议 3.10
librknnrt.so 找不到	库没有推到板子	adb push librknnrt.so /usr/lib/ && adb shell ldconfig
交叉编译的程序在板子上报 Exec format error	编译器选错了（用了 x86 GCC）	确认用 aarch64-none-linux-gnu-gcc，用 file 命令验证输出文件
ADB 连接后断开	USB 供电不稳	换质量好的 USB 线，或改用 SSH 连接
CMake 找不到交叉编译器	环境变量没生效	source ~/.bashrc 或重开终端
VSCode Remote-SSH 连接超时	板子 IP 变了（DHCP）	给板子配置静态 IP，或在路由器绑定 MAC

---

八、环境验证清单

搭建完成后，按以下清单逐项确认：

# ✅ 1. 交叉编译器正常
aarch64-none-linux-gnu-gcc --version

# ✅ 2. Python 环境正常
source ~/rknn-env/bin/activate
python3 -c "from rknn.api import RKNN; print('OK')"

# ✅ 3. ADB 或 SSH 能连板子
adb devices  # 或 ssh root@192.168.x.x

# ✅ 4. 板子上 RKNN 运行时库存在
adb shell "ls -la /usr/lib/librknnrt.so"

# ✅ 5. Hello World 能在板子上运行
# （参考第三节的验证步骤）

全部通过，开发环境搭建完成。

---

九、总结与下篇预告

本篇完成的工作：

• 交叉编译工具链安装与验证
• RKNN-Toolkit2 SDK 完整安装，理解了目录结构中每个关键文件的作用
• 板子 SSH 配置 + VSCode Remote-SSH 远程开发
• CMake 交叉编译工程模板

下一篇（系列第 3 篇）正式进入 RKNN SDK 使用，带你跑通第一个 AI 推理程序：用 MobileNetV2 做图像分类，完整走一遍"Python 模型转换 → C++ 板端推理 → 结果输出"的全流程。

---

本系列文章列表（持续更新）

• ✅ 第1篇：硬件全解析：NPU/CPU/GPU架构与芯片选型指南
• ✅ 第2篇：Linux 开发环境从零搭建（本文）
• 🔜 第3篇：RKNN SDK 快速上手
• 🔜 第4篇：模型转换全流程
• 🔜 第5篇：INT8 量化实战
• … … 共 16 篇