1. 为什么在 macOS 上折腾 STM32 开发环境如果你手里是一台 Mac又想玩 STM32第一反应大概率是「装个 Keil 或者 STM32CubeIDE 不就完了」。但真装过就知道STM32CubeIDE 在 macOS 上启动慢、吃内存而且它把编辑器和工具链绑死你想换个顺手的编辑器都难。我自己的做法是把三件事拆开STM32CubeMX 负责图形化生成初始化代码STM32CubeCLT 提供命令行工具链编译器、调试器、烧录器VS Code 负责写代码和跑任务。这样每一层都能单独替换环境也更干净。这套组合的核心检索词就是macOS 上 STM32CubeMX STM32CubeCLT VS Code 搭建嵌入式开发环境。它能做什么简单说你在 CubeMX 里点几下配置好时钟和引脚生成工程然后在 VS Code 里按一个快捷键就能编译、烧录、进调试。适合谁适合已经会一点 C 语言、想摆脱笨重 IDE 的嵌入式初学者也适合从 Windows 迁到 Mac 的老玩家。另外这篇文章还会多做一件事把 VS Code 里跟 AI 相关的 API endpoint 统一改到 TaoToken用一个 Key 管理多个模型的调用。这样你写代码时用的 AI 补全、代码解释和嵌入式工具链本身互不干扰但配置集中在一处换机器时复制一份 settings.json 就行。下面从零开始每一步都给可复制的命令和配置。2. 前置准备安装 STM32CubeMX、STM32CubeCLT 与 VS Code 插件这一节把三个基础软件装好。顺序建议是先装 STM32CubeCLT再装 STM32CubeMX最后配 VS Code。原因是 CubeMX 生成工程后需要调用 CLT 里的工具链先装 CLT 能少一次路径排查。STM32CubeCLT 是 ST 官方出的命令行工具链合集里面包含 arm-none-eabi-gcc、CMake、Ninja、OpenOCD、ST-LINK GDB Server 等。以前这些东西要一个个去 GitHub 找现在一个安装包搞定。去 ST 官网搜 STM32CubeCLT下载 macOS 版本.dmg双击安装。默认路径是/Applications/STM32CubeCLT_1.x.x/记住这个路径后面 tasks.json 要用。STM32CubeMX 是图形化配置工具同样在 ST 官网下载 macOS 版。它依赖 Java 运行环境新版安装包一般自带如果启动报 Java 相关错误去装一个 Temurin JDK 17 即可。安装完打开第一次会让你选芯片型号先随便选一个 STM32F103C8T6蓝板常用后面演示点灯就用它。VS Code 本身不用多说重点是插件。打开扩展面板搜索并安装STM32 VS Code Extension这是 ST 官方维护的插件装完它会自动检测 STM32CubeCLT 的路径。如果没检测到在插件设置里手动填/Applications/STM32CubeCLT_1.x.x。另外建议装 C/C 扩展微软官方和 CMake Tools前者提供代码跳转和补全后者方便你直接跑 CMake 工程。装完后验证一下工具链是否可用。打开终端执行export PATH/Applications/STM32CubeCLT_1.16.0/GNU-tools-for-STM32/bin:$PATH arm-none-eabi-gcc --version如果输出了 gcc 版本号说明工具链就绪。注意版本号1.16.0要换成你实际安装的版本。为了避免每次开终端都手动 export可以把这行加到~/.zshrc里。这一步做完你已经有了一套完整的命令行编译能力。接下来用 CubeMX 生成一个能编译的工程。3. 可复制配置CubeMX 生成工程 VS Code 的 settings.json 与 tasks.json先在 STM32CubeMX 里新建工程。选芯片 STM32F103C8T6进入引脚配置界面。把 PC13 设为 GPIO_Output这是蓝板上自带的 LED 引脚。然后在 Clock Configuration 里把 HCLK 设成 72MHzF103 的常见主频。接着切到 Project Manager 标签重点改三个地方Project Name 填blink_testProject Location 选一个你放代码的目录Toolchain/IDE 选CMake。选 CMake 是关键因为 STM32CubeCLT 用的是 CMake Ninja 构建选 Makefile 也能用但 CMake 更顺。点 Generate CodeCubeMX 会生成一整套工程包括Core/、Drivers/、CMakeLists.txt、cmake/等目录。用 VS Code 打开这个工程目录。现在配置 VS Code。在工程根目录建.vscode文件夹里面放两个文件。第一个是settings.json用来告诉 C/C 插件头文件在哪同时把 AI 相关的 API endpoint 统一到 TaoToken{ C_Cpp.default.includePath: [ ${workspaceFolder}/Core/Inc, ${workspaceFolder}/Drivers/STM32F1xx_HAL_Driver/Inc, ${workspaceFolder}/Drivers/STM32F1xx_HAL_Driver/Inc/Legacy, ${workspaceFolder}/Drivers/CMSIS/Device/ST/STM32F1xx/Include, ${workspaceFolder}/Drivers/CMSIS/Include ], C_Cpp.default.defines: [ USE_HAL_DRIVER, STM32F103xB ], cmake.generator: Ninja, cmake.buildDirectory: ${workspaceFolder}/build, taotoken.endpoint: https://taotoken.net/api, taotoken.apiKey: sk-你的TaoTokenKey }这里taotoken.endpoint和taotoken.apiKey是给支持自定义 endpoint 的 AI 插件读的不同插件字段名可能不同但思路一致Base URL 填https://taotoken.net/apiKey 填你在 TaoToken 控制台生成的。这样你所有 AI 辅助功能都走同一个 Key不用每个插件单独配。第二个文件是tasks.json定义编译、烧录、调试三个任务{ version: 2.0.0, tasks: [ { label: build, type: shell, command: cmake, args: [--build, ${workspaceFolder}/build], options: { env: { PATH: /Applications/STM32CubeCLT_1.16.0/GNU-tools-for-STM32/bin:/Applications/STM32CubeCLT_1.16.0/Ninja/bin:${env:PATH} } }, group: { kind: build, isDefault: true }, problemMatcher: [$gcc] }, { label: flash, type: shell, command: STM32_Programmer_CLI, args: [ -c, portSWD, -w, ${workspaceFolder}/build/blink_test.elf, -v, -rst ], dependsOn: [build], problemMatcher: [] } ] }注意blink_test.elf这个名字要跟你 CubeMX 里填的 Project Name 一致。STM32_Programmer_CLI在 CLT 的bin目录下如果终端找不到把它的绝对路径写进 command。配置完这两个文件按CmdShiftB就能触发 build 任务。第一次构建前需要先跑一次 CMake 配置cd /你的工程路径/blink_test cmake -B build -G Ninja \ -DCMAKE_TOOLCHAIN_FILEcmake/gcc-arm-none-eabi.cmake \ -DCMAKE_BUILD_TYPEDebug这条命令生成 build 目录和 Ninja 构建文件。之后每次改代码直接cmake --build build就行。4. 验证请求编译点灯工程并烧录到开发板配置写完了现在验证整条链路。先改一下Core/Src/main.c在while (1)循环里加两行HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13); HAL_Delay(500);保存后按CmdShiftB终端会输出类似[build] [1/3] Building C object CMakeFiles/blink_test.dir/Core/Src/main.c.obj [build] [2/3] Linking C executable blink_test.elf [build] [3/3] Built target blink_test看到Built target就说明编译通过。如果报arm-none-eabi-gcc: command not found检查 tasks.json 里的 PATH 是否指向你实际的 CLT 版本目录。接下来烧录。把 ST-LINK 调试器插上开发板供电。运行 flash 任务或者手动执行STM32_Programmer_CLI -c portSWD -w build/blink_test.elf -v -rst成功的话会看到Memory Programming ... Download verified successfully Software reset is performed板子上的 PC13 LED 应该开始以 1Hz 闪烁。到这一步编译、烧录链路就通了。再验证一下 TaoToken 的 Key 是否生效。如果你用的 AI 插件支持自定义 endpoint在插件里发一条测试请求比如让它解释HAL_GPIO_TogglePin的作用。请求会发到https://taotoken.net/api带上你的 Key。返回正常就说明统一 Key 配置成功。这一步的意义在于以后你换模型、换插件只要改 settings.json 里的 endpoint 和 Key不用每个工具重新登录。调试部分VS Code 里可以配 launch.json 走 OpenOCD 或 ST-LINK GDB Server。因为本文重点是环境搭建和编译烧录调试配置留到下一篇展开。你先把编译和烧录跑通这已经能覆盖大部分日常开发。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth环境搭建过程中最容易卡在几个报错上这里逐个对照。401 Unauthorized这个通常出现在 AI 插件请求 TaoToken 时。原因一般是 Key 没填对或者 Key 前面多了空格。检查 settings.json 里taotoken.apiKey的值确保是sk-开头、没有换行。另外确认 endpoint 是https://taotoken.net/api不要漏掉/api后缀。如果还报 401去 TaoToken 控制台重新生成一个 Key 替换。local proxy failed这个报错说明插件尝试走本地代理但失败了。先检查系统代理设置把无关的代理关掉。然后在插件配置里确认没有填http://127.0.0.1:xxxx这类本地地址。TaoToken 的 endpoint 是直连的 HTTPS 地址不需要本地代理。如果插件默认开了代理选项关掉它。reading choices 相关报错这通常出现在请求返回格式不符合预期时比如插件期望 OpenAI 格式的choices数组但返回了别的结构。检查你用的模型 ID 是否跟插件兼容。在 TaoToken 的模型对话页面可以先用同一个 Key 测一下模型是否正常返回。如果模型对话正常但插件报错多半是插件版本旧了升级插件。OAuth 相关报错有些 AI 插件默认走 OAuth 登录而不是 API Key。如果你看到 OAuth 回调失败或者 token 过期去插件设置里把认证方式从 OAuth 改成 API Key填入 TaoToken 的 Key。这样就不依赖第三方登录流程了。编译报错No such file or directory: cmake/gcc-arm-none-eabi.cmake这是 CubeMX 生成工程时 Toolchain 没选 CMake或者你手动删了 cmake 目录。重新用 CubeMX 生成一次Toolchain 选 CMake。烧录报错No ST-LINK detected检查 USB 线是否支持数据传输有些线只能充电检查 ST-LINK 驱动macOS 上一般免驱。如果用的是板载 ST-LINK确认跳线帽位置正确。排查思路就是先确认工具链路径对不对再确认 Key 和 endpoint 对不对最后确认硬件连接。大部分问题出在前两步。6. 统一 Key 之后把 AI 辅助接入日常嵌入式开发环境跑通后你可以把 TaoToken 的 Key 用在更多地方。比如在 VS Code 里装一个支持自定义 endpoint 的 AI 编程插件把 Base URL 填https://taotoken.net/apiKey 填同一个Model ID 填你常用的模型。这样写代码时遇到不认识的 HAL 函数直接选中问 AI不用切浏览器。如果你长期做嵌入式开发建议了解一下 Coding Plan它适合需要频繁调用模型做代码生成、解释、重构的场景。配置入口在 TaoToken 控制台的 API Keys 页面生成 Key 后回到插件里填就行。接入文档里有不同插件的详细字段说明遇到字段名对不上时查一下。模型对话页面可以用来快速验证 Key 是否有效也可以对比不同模型对同一段 C 代码的解释质量。我一般先用模型对话测通再配到插件里这样出问题能快速定位是 Key 的问题还是插件的问题。最后提醒一点settings.json 和 tasks.json 建议纳入版本管理但 Key 不要提交到 Git。可以把 Key 放在环境变量里settings.json 里引用${env:TAOTOKEN_API_KEY}这样换机器时只需设置一次环境变量。整套环境搭好后你在一台新 Mac 上从零到点灯大概 20 分钟就能搞定。