概述
在 Linux 上开发 Ai-WB2 是官方最推荐的方式：一条 apt 命令装依赖、一条 git clone 拉 SDK、一条 make 编译，全程无需图形界面。本教程按官方 README 的完整流程（安装依赖 → 克隆 SDK → 工具链授权 → 编译 → 烧录），带你用官方 helloworld 示例跑通第一个程序。
用大白话讲：环境搭建就像「装修厨房」——先备好锅碗瓢盆（依赖软件），再把菜谱（SDK）搬到家里，最后开火试做一道菜（编译并烧录 helloworld）。本教程做完，你的电脑就具备了完整的开发能力，后面的教程都是「照着菜谱做菜」。
本教程基于安信可官方 SDK（Ai-Thinker-Open/Ai-Thinker-WB2，版本
release_bl_iot_sdk_1.6.40）的官方 README（仓库根目录README.md）编写，安装流程与官方文档完全一致。
打开终端（快捷键 Ctrl + Alt + T），执行官方提供的一行安装命令：
sudo apt install build-essential python3 python3-pip git screen
说明：
sudo表示以管理员权限执行（会提示输入你的开机密码）；apt install是 Ubuntu 的软件安装命令；这里一次装齐 5 个软件——build-essential（C 编译器 gcc/make 等编译工具）、python3（构建脚本依赖）、python3-pip（Python 包管理）、git（拉取代码）、screen（串口查看日志用）。
安装完成后验证是否成功：
make --version && git --version
看到类似 GNU Make 4.x 和 git version 2.x 的输出即安装成功。
⚠️ 如果
sudo apt install非常慢或报错，通常是软件源在国外导致，先更换国内软件源（清华/阿里源）再重试。可参考网上「Ubuntu 更换国内源」教程，或直接改用国内 Gitee 镜像（见下一步）。
在终端执行（官方 README 原文，--recursive 必须带上，用于拉取子模块）：
git clone --recursive https://gitee.com/Ai-Thinker-Open/Ai-Thinker-WB2.git
说明：
git clone是「下载仓库」命令，--recursive表示连同子模块一起下载。国内网络下载 GitHub 慢或失败时，改用官方提供的 Gitee（码云）镜像，内容完全一致：
git clone --recursive https://gitee.com/Ai-Thinker-Open/Ai-Thinker-WB2.git
下载完成后（进度条走满、回到命令提示符），确认目录存在：
ls ~/Ai-Thinker-WB2
能看到 applications、components、toolchain 等目录即克隆成功。
💡 默认克隆到当前用户主目录（
~即/home/你的用户名/），后续所有教程的cd ~/Ai-Thinker-WB2/applications/...都基于这个位置。想换目录可以自己改，但建议保持默认。
工具链刚下载下来还没有「可执行」权限，需要执行官方提供的授权脚本。在 SDK 根目录执行：
cd ~/Ai-Thinker-WB2/toolchain/riscv/Linux/
. chmod755.sh
说明：
cd是「进入目录」；. chmod755.sh是「执行当前目录下的授权脚本」（开头的.是source的简写，表示在本终端里执行），它会把工具链里所有文件加上可执行权限。执行过程没有任何输出是正常的，直接进入下一步。
验证工具链可用：
./riscv64-unknown-elf-gcc --version
说明：此命令直接运行工具链的编译器并打印版本，能输出版本号就说明授权成功。若报
Permission denied（没有权限），说明上一步没有执行成功，回到上一步重试。
进入官方入门示例工程，执行编译：
cd ~/Ai-Thinker-WB2/applications/get-started/helloworld
make -j8
说明：
make是「编译」命令（把 C 代码变成开发板能运行的固件），-j8表示 8 个任务并行编译更快。必须在 helloworld 工程目录内执行（刚才cd已进入）。首次编译需要几分钟（要编译整个 SDK 组件），之后增量编译很快。
编译成功后会生成固件 build_out/helloworld.bin，并显示：
✓ Built target helloworld
看到这行即编译成功。
⚠️ 若报
./riscv64-unknown-elf-gcc: No such file or directory或Permission denied，说明步骤③的授权没做对，回到步骤③重新执行. chmod755.sh。
开发板用 Type-C 数据线连接电脑，先确认串口设备号：
ls /dev/ttyUSB*
说明：
ls是「列出」命令，/dev/ttyUSB*是串口设备路径的统称。能看到类似/dev/ttyUSB0的输出说明开发板已被识别；什么都看不到说明数据线只能充电不能传数据、或需要装 USB 转串口驱动（Linux 一般免驱，多为线材问题，换线重试）。
然后执行烧录：
make flash p=/dev/ttyUSB0 b=921600
说明：
p=是串口设备号（以你上一步ls看到的为准，不一定都是ttyUSB0）；b=是烧录波特率（传输速度），官方固定921600。
看到 Waiting for download... 之类的提示时，长按开发板上的 EN 键（RST 复位键）约 1 秒后松开，开发板进入下载模式，进度条开始走动。
⏳ 进度条走到 100% 并提示烧录完成即成功。若一直停在等待状态，多半是 EN 键没按对，重按一次试试。
烧录完成后开发板自动重启运行程序。用 screen 打开串口观察输出（官方安装的 screen 就是干这个的）：
screen /dev/ttyUSB0 921600
说明：
screen是串口查看工具，/dev/ttyUSB0换成你的串口号，921600是波特率——必须和烧录时一致，否则看到的是乱码。
屏幕持续打印启动日志，重点看这几行：
Hello World.
Restarting in 10 seconds...
Restarting in 9 seconds...
看到 Hello World. 和倒计时，说明开发板已经跑起来了——你的第一个程序成功！
💡 官方示例会倒计时 10 秒后自动重启开发板（相当于测试软复位），这是正常的。看完日志按
Ctrl + A再按K退出 screen（提示时按y确认）。
💡 进阶验证：日志开头还有
Build Version: release_bl_iot_sdk_1.6.38之类的一行，那是固件编译时的 SDK 版本号，不同批次可能不同，不影响使用。
代码执行流程
例程从启动到运行的完整流程如下（图中的循环箭头表示反复执行）：
本文用到的命令汇总
sudo apt install(软件包列表)
以管理员权限安装 Ubuntu 软件（本教程用于安装编译依赖：build-essential/python3/git/screen）。
参数：
- 软件包列表：空格分隔的软件名，如
build-essential python3 git screen
返回值：安装完成回到提示符即成功；中途报错（网络问题）换源后重试
git clone --recursive(仓库地址)
下载 SDK 仓库及全部子模块到当前目录（国内网络推荐 Gitee 镜像地址）。
参数：
--recursive：递归拉取子模块，必加（否则部分组件是空的）- 仓库地址：
https://gitee.com/Ai-Thinker-Open/Ai-Thinker-WB2.git或 Gitee 镜像
返回值：进度条走满回到提示符即成功
. chmod755.sh
执行工具链授权脚本，给编译器加可执行权限（Linux 下下载的文件默认没有执行权限）。
参数：
- 无（在
~/Ai-Thinker-WB2/toolchain/riscv/Linux/目录内执行）
返回值：无输出即正常；Permission denied 说明没执行成功
make flash(p=串口设备 b=波特率)
把固件烧录进开发板（烧录时需按开发板 EN 键进入下载模式）。
参数：
p=：串口设备号，如/dev/ttyUSB0（先用ls /dev/ttyUSB*确认）b=：波特率，官方固定921600
返回值：进度条 100% 即成功；一直等待说明没进下载模式
完整代码（参考：helloworld/main.c）
以下为官方 helloworld 示例源码，与官方（applications/get-started/helloworld/helloworld/main.c）完全一致。它打印 Hello World. 后倒计时 10 秒自动重启开发板，是验证环境是否装好的「体检程序」：
📜 点击展开 helloworld/main.c 完整代码
/*
* @Author: xuhongv@yeah.net xuhongv@yeah.net
* @Date: 2022-10-03 15:02:19
* @LastEditors: xuhongv@yeah.net xuhongv@yeah.net
* @LastEditTime: 2022-10-08 14:55:16
* @FilePath: \bl_iot_sdk_for_aithinker\applications\get-started\helloworld\helloworld\main.c
* @Description: Hello world
*/
#include <stdio.h>
#include <string.h>
#include <FreeRTOS.h>
#include <task.h>
#include <blog.h>
#include "bl_sys.h"
void main(void)
{
printf("Hello World.\r\n");
for (int i = 10; i >= 0; i--)
{
printf("Restarting in %d seconds...\r\n", i);
vTaskDelay(1000 / portTICK_PERIOD_MS);
}
printf("Restarting now.\r\n");
bl_sys_reset_por();
}常见问题与踩坑提示
⚠️ sudo apt install 很慢或失败
原因：默认软件源在国外，国内网络访问慢
解决：先更换国内软件源（清华/阿里镜像源，网上搜「Ubuntu 换源」有图文教程），换完再重新执行安装命令
⚠️ git clone 卡住或报错
原因：GitHub 在国内网络不稳定，大仓库（SDK 含子模块有几百 MB）容易断
解决：改用 Gitee 镜像 git clone --recursive https://gitee.com/Ai-Thinker-Open/Ai-Thinker-WB2.git；断线后重新执行即可断点续传
⚠️ 编译报 riscv64-unknown-elf-gcc: No such file or directory 或 Permission denied
原因：工具链没授权（步骤③没做或做错），编译器没有可执行权限
解决：回到 SDK 根目录重新执行 cd toolchain/riscv/Linux/ 和 . chmod755.sh，再验证 ./riscv64-unknown-elf-gcc --version 能输出版本
⚠️ make 报 make: command not found
原因：步骤①的 build-essential 没装上
解决：执行 sudo apt install build-essential 补装，再验证 make --version
⚠️ ls /dev/ttyUSB 什么都看不到*
原因：数据线只能充电不能传数据、或开发板没插好
解决：换一根能传数据的 Type-C 数据线；拔插后重试；还不行用 dmesg | tail 看系统日志有没有 USB 识别记录
⚠️ 烧录一直 Waiting for download / 进度条不动
原因：没有按 EN 键进入下载模式，或串口号写错
解决：看到等待提示时长按 EN（RST）键约 1 秒松开；确认 p= 的串口号和 ls /dev/ttyUSB* 看到的一致
⚠️ 串口打开报 Permission denied（权限不足）
原因：当前用户不在 dialout 用户组，无权访问串口
解决：执行 sudo usermod -aG dialout 你的用户名，然后注销重新登录（或重启）使配置生效
运行自检
烧录后在串口看到 Hello World. 以及 Restarting in 10 seconds... 倒计时输出，即 Linux 环境搭建验证通过，可以开始 GPIO输出(点亮LED) 了。
遇到问题？
如有其他问题，请到统一的提问与讨论区：Ai-Thinker Discussions