1. 环境准备与Docker配置

第一次接触启航kp开发板和OpenHarmony时，我被复杂的开发环境配置劝退过三次。直到发现Docker这个神器，原来半小时就能搞定所有依赖。这里分享我的避坑指南，帮你跳过那些让我抓狂的坑。

Docker环境配置 就像给开发板准备一个标准化公寓。我推荐使用Ubuntu 20.04系统，实测这个版本对OpenHarmony支持最稳定。先运行这两个命令确保系统最新：

sudo apt update
sudo apt upgrade -y

安装Docker时最容易卡在镜像源配置。国内开发者一定要用国内源，否则下载速度会让你怀疑人生。这是我验证过的阿里云Docker安装方案：

curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable"
sudo apt install docker-ce docker-ce-cli containerd.io

装完记得把当前用户加入docker组，否则每次都要sudo：

sudo usermod -aG docker $USER
newgrp docker  # 立即生效

验证安装 时别只用docker --version，我遇到过能显示版本但实际无法运行的情况。一定要跑个测试容器：

docker run hello-world

看到那个可爱的"Hello from Docker!"说明环境OK了。接下来获取专为OpenHarmony定制的Docker镜像，华为云镜像站的速度比Docker Hub快5倍不止：

docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0

启动容器时有个 重要技巧 ：用-v参数把本地目录挂载到容器里。我专门创建了~/openharmony目录存放代码，这样容器销毁后代码也不会丢失：

docker run -it -v ~/openharmony:/home/openharmony openharmony-docker:1.0.0

2. 源码获取与开发板适配

进入容器后第一件事是获取源码，这里有个血泪教训：一定要先设置git全局配置！我第一次同步代码时因为没设邮箱导致中途失败，8GB的代码白下了。

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

对于启航kp开发板，建议使用 3.2 Release 分支，兼容性最好。同步代码时用-c参数只拉取当前分支，能节省一半时间：

repo init -u https://gitee.com/openharmony/manifest.git -b OpenHarmony-3.2-Release -g ohos:mini
repo sync -c

看到"repo sync has completed"提示后，别急着高兴，还要拉取大文件：

repo forall -c 'git lfs pull'

开发板适配 是新手最容易懵的环节。启航kp需要添加两个关键目录：

1. 把开发板提供的vendor_isoftstone/qihang放到vendor/isoftstone下
2. 把board_qihang内容放到device/board/isoftstone/qihang

就像给新房添置家具，放错位置就识别不到。用tree命令检查目录结构应该是这样：

openharmony
├── vendor
│   └── isoftstone
│       └── qihang
└── device
    └── board
        └── isoftstone
            └── qihang

验证配置是否成功，运行hb set命令应该能看到"qihang"选项。如果没出现，检查目录权限是不是755。

3. 编写第一个Hello World应用

在device/board/isoftstone/qihang/app下新建01hello目录，这里要注意： 目录名不要用中文 ！我当初用"测试"命名导致编译失败，排查了两小时。

创建hello.c文件，内容如下：

#include <stdio.h>
#include "ohos_init.h"

void hello_demo(void) {
    printf("Hello OpenHarmony!\n");
}

SYS_RUN(hello_demo);

重点说明：SYS_RUN这个宏相当于main函数，是OpenHarmony的特色机制。没有它，你的代码就像没有插电的电器，永远无法启动。

接着创建BUILD.gn文件，这个相当于Makefile：

static_library("hello_demo") {
    sources = ["hello.c"]
    include_dirs = [
        "//utils/native/base/include"
    ]
}

最后修改app目录下的BUILD.gn，添加我们的模块：

lite_component("app") {
    features = [
        "01hello:hello_demo",
    ]
}

4. 编译与烧录实战

编译前建议先执行以下命令，避免缓存问题：

hb clean

选择开发板配置时，用方向键选择"qihang"后回车：

hb set

开始编译时加上-f参数强制重新生成，我第一次没加这个参数，修改的代码死活不生效：

hb build -f

看到"qihang build success"提示后，在out/qihang/qihang目录下找到Hi3861_wifiiot_app_allinone.bin文件。用VS Code的Dev Containers扩展可以直接在容器内操作，比命令行更方便。

烧录到启航kp开发板时要注意：

1. 按住BOOT键再按RST键进入烧录模式
2. 使用HiBurn工具选择xmodem协议
3. 波特率设置为921600

成功运行后，在串口终端会看到"Hello OpenHarmony!"输出。如果没显示，检查开发板供电是否稳定，我遇到过因为USB口供电不足导致程序跑飞的情况。

5. 进阶调试技巧

printf调试太原始？试试OpenHarmony的 hilog 系统，像这样修改代码：

#include "hilog/log.h"
#define LOG_DOMAIN 0x1234
#define LOG_TAG "HELLO"

void hello_demo(void) {
    HILOG_INFO(LOG_APP, "This is a log message!");
}

编译烧录后，用以下命令查看日志：

hilog | grep HELLO

遇到崩溃时，在BUILD.gn中添加调试符号：

static_library("hello_demo") {
    # 新增下面两行
    cflags = ["-g"]
    strip = false
}

这样用gdb调试时就能看到具体崩溃位置。建议在VS Code里配置C++调试环境，比命令行gdb友好十倍。

6. 常见问题解决方案

问题1 ：hb set找不到qihang选项

• 检查device和vendor目录结构是否正确
• 确认qihang目录权限是755
• 删除out目录后重试

问题2 ：编译时报错头文件找不到

• 在BUILD.gn中添加include_dirs
• 检查ohos_init.h是否来自正确版本

问题3 ：烧录后无输出

• 确认开发板串口接线正确
• 检查波特率设置
• 尝试重新擦除整片再烧录

我收集了20多个常见错误和解决方案，都整理在GitHub的issue里。遇到问题时可以先搜索错误代码，90%的问题都有现成答案。