企业官网建设流程全解析

1. 为什么我彻底放弃了MDK5转投PlatformIO

1.1 一个用了五年MDK的老用户的真实心路

先说结论：我不是因为MDK5不能用才换的，而是因为用久了之后发现，它拖慢我效率的地方实在太多了。STM32F103C8T6这颗芯片，圈子里叫它"蓝板"或者"最小系统板"，几乎每个搞嵌入式的人都拿它入门过。我手上这块板子买了三年，前两年一直用MDK5写标准库工程，直到去年开始接一些需要频繁切换芯片型号和工程配置的活，才痛下决心把整个工具链迁到PlatformIO+VSCode上。

MDK5的问题不在于它不能编译，而在于它的工程管理方式太"重"了。每次新建一个STM32F103C8T6的标准库工程，你得手动建目录、复制启动文件、复制标准外设库的src和inc、配置Include Paths、勾选宏定义、设置下载算法……一套流程走下来，顺利的话十五分钟，不顺利的话半小时就没了。而且MDK5的代码补全和跳转体验，说实话停留在十年前的水平，遇到标准库那种层层嵌套的结构体，想看一个寄存器的定义要跳好几次。

PlatformIO本质上是一个跨平台的嵌入式构建系统，它跑在VSCode里面，用Python写的构建核心，支持上千种开发板和框架。你只需要在配置文件里写几行参数，它自动帮你下载对应的编译工具链、框架代码和上传工具。对于STM32F103C8T6来说，你可以选择Arduino框架、CMSIS框架，也可以选择我们这篇文章要重点讲的标准外设库框架。

1.2 这套方案到底适合谁

如果你符合下面任意一条，这套环境值得你花一个下午搭起来：

• 手上有STM32F103C8T6最小系统板，想用标准库开发但不想装MDK5
• 已经会用MDK5写标准库，但受够了它的编辑体验和工程管理
• 想在一个编辑器里同时写STM32、ESP32、Python脚本和前端代码
• 团队协作时需要把工程配置纳入版本管理，而不是靠"我的MDK配置截图"

不适合的情况也说清楚：如果你做的是需要特定编译器优化或者依赖MDK独有中间件的项目，比如某些需要ARM Compiler 5特定行为的遗留代码，那暂时别折腾。另外如果你完全没接触过C语言和单片机，建议先用Arduino框架跑通点灯，再回来搞标准库。

1.3 迁移前你需要知道的几个关键差异

从MDK5迁到PlatformIO，最大的思维转变在于：工程配置从图形界面变成了文本文件。MDK5里你点鼠标勾选的那些选项，在PlatformIO里全部写在platformio.ini这个文件里。刚开始会不习惯，但一旦习惯了之后你会发现，这个文件可以提交到Git，可以复制给同事，可以在不同电脑上一键还原环境。

第二个差异是编译工具链。MDK5用的是ARM Compiler，PlatformIO默认用GCC ARM工具链。两者在语法支持上基本一致，但GCC对某些非标准写法更严格，比如MDK里能过的隐式类型转换，GCC可能会给warning。这不是坏事，反而帮你写出更规范的代码。

第三个差异是下载和调试。MDK5配合ST-Link用起来很顺，PlatformIO同样支持ST-Link，通过OpenOCD或者stlink工具上传。调试方面PlatformIO支持GDB调试，配合Cortex-Debug插件可以做到断点、单步、看寄存器，体验不比MDK差。

2. 环境搭建的完整实操流程

2.1 VSCode和PlatformIO插件的安装细节

VSCode去官网下载对应系统的安装包，Windows用户注意勾选"添加到PATH"，这样后面命令行操作方便。安装完成后第一件事是装中文语言包，在扩展面板搜索"Chinese"就能找到官方简体中文包。然后搜索"PlatformIO IDE"安装，这个插件比较大，会连带下载Python环境和一堆工具，安装过程视网络情况可能要五到十分钟。

安装完成后左侧会出现一个蚂蚁头图标，那就是PlatformIO的主页。第一次打开它会自动初始化，下载核心组件。这里有个坑：如果你的网络环境访问国外源比较慢，初始化可能会卡住。解决办法是配置国内镜像源，在用户目录下创建.platformio文件夹，里面放一个platformio.ini全局配置，加上镜像地址。具体地址我就不贴了，搜"PlatformIO 国内镜像"能找到最新的。

注意：PlatformIO插件安装过程中不要关闭VSCode，也不要中途断网，否则可能导致Python环境损坏，修复起来很麻烦。

2.2 创建STM32F103C8T6标准库工程的正确姿势

打开PlatformIO主页，点"New Project"，填写工程名称，Board那一栏搜索"STM32F103C8"，选择"ST STM32F103C8 (BluePill)"或者通用的"Generic STM32F103C8"。Framework选择"CMSIS"，因为标准库本质上就是基于CMSIS的。Location选一个没有中文和空格的路径，这点很重要，中文路径会导致编译工具链报错。

创建完成后你会看到工程目录结构：src放源文件，include放头文件，lib放自定义库，platformio.ini是配置文件。默认生成的main.c是一个空的CMSIS工程，我们要把它改造成标准库工程。

2.3 标准外设库文件的获取与目录规划

标准外设库，也就是ST官方出的Standard Peripheral Library，最新版本是V3.5.0。这个库ST已经不再维护了，但网上到处都能下载到。下载下来解压后，你会看到Libraries文件夹，里面有STM32F10x_StdPeriph_Driver，这就是核心。

我的做法是在工程根目录下建一个lib文件夹，里面再建STM32F10x_StdPeriph_Driver，把src和inc两个文件夹复制进去。然后把CMSIS相关的文件也整理进来：core_cm3.h、stm32f10x.h、system_stm32f10x.h、system_stm32f10x.c、启动文件startup_stm32f10x_md.s。启动文件要根据芯片容量选，STM32F103C8T6是64KB Flash，属于中等容量，选md后缀的。

目录结构建议这样组织：

project/ ├── lib/ │ ├── STM32F10x_StdPeriph_Driver/ │ │ ├── inc/ │ │ └── src/ │ └── CMSIS/ │ ├── core_cm3.h │ ├── stm32f10x.h │ ├── system_stm32f10x.h │ └── system_stm32f10x.c ├── src/ │ ├── main.c │ ├── stm32f10x_it.c │ └── startup_stm32f10x_md.s ├── include/ │ └── stm32f10x_conf.h └── platformio.ini

2.4 platformio.ini的关键配置逐行解读

这是整个工程最核心的文件，我直接贴出我实际在用的配置，然后逐行解释：

[env:bluepill_f103c8] platform = ststm32 board = bluepill_f103c8 framework = cmsis upload_protocol = stlink debug_tool = stlink build_flags = -I lib/CMSIS -I lib/STM32F10x_StdPeriph_Driver/inc -I include -D STM32F10X_MD -D USE_STDPERIPH_DRIVER -D HSE_VALUE=8000000 build_src_filter = +<../lib/STM32F10x_StdPeriph_Driver/src/*.c> +<../lib/CMSIS/system_stm32f10x.c> +<../src/*.c> +<../src/*.s>

platform = ststm32指定平台是ST的STM32系列。board = bluepill_f103c8指定板子型号，这个决定了默认的编译参数和上传配置。framework = cmsis表示用CMSIS框架，标准库就是建立在这个基础上的。

upload_protocol = stlink和debug_tool = stlink指定用ST-Link下载和调试。如果你用的是串口下载，改成upload_protocol = serial，然后指定端口。

build_flags里的-I是头文件搜索路径，-D是宏定义。STM32F10X_MD告诉库我们用的是中等容量芯片，USE_STDPERIPH_DRIVER启用标准外设库，HSE_VALUE=8000000指定外部晶振是8MHz，这个值影响系统时钟配置。

build_src_filter告诉PlatformIO哪些源文件要参与编译。默认它只编译src目录，我们加了lib下的标准库源文件和启动文件。

提示：build_src_filter里的路径是相对于platformio.ini所在目录的，+<表示包含，-<表示排除。如果你发现某个文件没被编译，先检查这里。

3. 标准库工程的核心文件配置

3.1 stm32f10x_conf.h的裁剪与配置

这个文件是标准库的总开关，里面通过#include的方式决定哪些外设驱动参与编译。默认的模板把所有外设都打开了，但实际项目里你可能只用GPIO、USART和TIM，其他的可以注释掉，能省不少编译时间。

#ifndef __STM32F10x_CONF_H #define __STM32F10x_CONF_H #include "stm32f10x_gpio.h" #include "stm32f10x_rcc.h" #include "stm32f10x_usart.h" #include "stm32f10x_tim.h" #include "misc.h" #endif

misc.h是NVIC和SysTick的配置函数，中断相关的项目必须包含。如果你要用DMA，加上stm32f10x_dma.h；要用ADC，加上stm32f10x_adc.h。这个文件放在include目录下，因为stm32f10x.h里会引用它。

3.2 系统时钟配置的常见坑

STM32F103C8T6最小系统板上的晶振通常是8MHz，但有些廉价板子焊的是12MHz甚至没有晶振。如果你发现串口输出的波特率不对，十有八九是时钟配置和实际晶振不匹配。

标准库的system_stm32f10x.c里默认把系统时钟配到72MHz，前提是HSE是8MHz。配置流程是：使能HSE，等待稳定，配置PLL倍频到9倍，选择PLL作为系统时钟源。如果你板子上是12MHz晶振，需要把PLL倍频改成6倍，同时HSE_VALUE改成12000000。

我实测过几块不同批次的蓝板，有的晶振负载电容不匹配，起振很慢甚至不起振。判断方法是写个点灯程序，如果灯闪得比预期慢很多，可能就是HSE没起来，系统自动切到了内部8MHz RC振荡器。解决办法是在SystemInit里加超时判断，起振失败就切HSI。

3.3 启动文件的选择与中断向量表

启动文件startup_stm32f10x_md.s里定义了中断向量表，每个中断服务函数的弱符号都指向一个死循环。你要在stm32f10x_it.c里重写对应的函数，比如USART1_IRQHandler，否则中断触发后就会卡在死循环里。

这里有个容易忽略的点：启动文件里的栈大小和堆大小。默认栈是0x400也就是1KB，如果你用了比较大的局部数组或者递归，可能会栈溢出。我一般把栈改成0x800，堆保持0x200。改的位置在启动文件开头：

Stack_Size EQU 0x00000800 Heap_Size EQU 0x00000200

栈溢出是嵌入式里最难查的bug之一，表现是程序跑飞或者变量莫名其妙被改。如果你遇到这类问题，先把栈加大试试。

3.4 链接脚本与内存布局

PlatformIO默认的链接脚本会把Flash起始地址设为0x08000000，RAM起始地址0x20000000，大小20KB。STM32F103C8T6的Flash是64KB，RAM是20KB，这些默认值是对的。但如果你用了Bootloader，需要把起始地址偏移，就要自己写链接脚本。

在platformio.ini里加一行board_build.ldscript = my_custom.ld，然后把你改过的链接脚本放在工程根目录。链接脚本里主要改FLASH和RAM的ORIGIN和LENGTH。这个操作不常用，但做OTA升级或者双区备份的时候必须掌握。

4. 编译、下载与调试的实操记录

4.1 第一次编译常见报错与解决

第一次点编译按钮，大概率会遇到几个报错。最常见的是undefined reference to 'SystemInit'，这是因为system_stm32f10x.c没被编译进去。检查build_src_filter里有没有包含这个文件。

第二个常见报错是cannot open source input file "stm32f10x.h"，这是头文件路径没配对。确认build_flags里的-I路径是否正确，注意大小写，Linux下路径大小写敏感。

第三个是region RAM overflowed，说明你的变量太多，20KB RAM不够用了。STM32F103C8T6的RAM确实小，用标准库的时候要注意少用大数组，能用const放Flash的就放Flash。

4.2 ST-Link下载配置与接线

ST-Link和蓝板的接线是：SWDIO接PA13，SWCLK接PA14，GND接GND，3.3V接3.3V。注意有些ST-Link的3.3V是输出，有些是输入，接反了可能烧。保险起见先只接SWDIO、SWCLK和GND三根线，用板子自己的USB供电。

在platformio.ini里配置好upload_protocol = stlink后，点上传按钮就会自动编译并下载。如果报st-link not found，检查驱动装没装，Windows下需要装ST-Link的USB驱动。Linux下需要配置udev规则，否则普通用户没权限访问USB设备。

4.3 用GDB做断点调试的配置

PlatformIO的调试功能需要装Cortex-Debug插件。装好后在platformio.ini里加上debug_tool = stlink，然后点左侧的调试按钮，会自动启动OpenOCD和GDB，停在main函数入口。

调试界面里可以看变量、看寄存器、看内存，还可以在platformio.ini里配置debug_init_break指定初始断点位置。我一般设成main，这样一启动就停在主函数，方便单步跟初始化流程。

有个小技巧：调试的时候如果发现断点打不上，检查优化等级。PlatformIO默认Debug构建是-Og，如果platformio.ini里手动设了-O2，断点可能会被优化掉。调试阶段建议用默认优化等级。

4.4 串口打印的配置与printf重定向

标准库工程里用printf需要重定向fputc函数。在main.c里加上：

#include <stdio.h> int fputc(int ch, FILE *f) { while (USART_GetFlagStatus(USART1, USART_FLAG_TC) == RESET); USART_SendData(USART1, (uint8_t)ch); return ch; }

然后在初始化里配好USART1，波特率115200，8位数据，1位停止，无校验。注意fputc里的USART_FLAG_TC是发送完成标志，不是发送数据寄存器空标志。用TC能保证数据真正发出去了，不会因为发送太快丢数据。

注意：用了printf之后，链接时会引入标准库的printf实现，代码体积会增加几KB。如果Flash紧张，可以用iprintf或者自己写个轻量级的串口打印函数。

5. 从MDK5迁移的避坑指南

5.1 编译器差异导致的代码修改

MDK的ARM Compiler和GCC在几个地方行为不同。第一是__weak关键字，MDK里写__weak，GCC里要写__attribute__((weak))。标准库的启动文件已经处理好了，但你自己写回调的时候要注意。

第二是内联汇编的语法不同。MDK用__asm，GCC用__asm__ volatile。如果你用了__NOP()这类CMSIS内联函数，一般没问题，但手写汇编就要改。

第三是位域的对齐方式。MDK默认按4字节对齐，GCC默认按实际类型对齐。标准库的寄存器定义都是uint32_t，不受影响，但你自己定义的结构体如果用了位域，跨编译器可能会有差异。

5.2 中断服务函数的重定义问题

MDK工程里中断服务函数写在stm32f10x_it.c里，PlatformIO工程里也一样。但要注意，如果你在多个文件里定义了同一个中断函数，GCC会报重复定义错误，而MDK可能只是给个warning。所以确保每个中断函数只在一个地方定义。

另外，标准库的启动文件里所有中断都是弱定义，你重写的时候函数名必须完全一致，包括大小写。USART1_IRQHandler不能写成Usart1_IRQHandler，否则链接不会报错，但中断触发时会跳到默认的死循环。

5.3 下载算法与Flash编程的差异

MDK5用ST-Link下载时用的是ST官方的Flash算法，PlatformIO用OpenOCD的Flash驱动。两者在大多数情况下都能正常烧写，但如果你遇到烧写失败，可以试试在platformio.ini里加upload_flags = -c set CPUTAPID 0x1ba01477，强制指定TAP ID。

还有一个情况是芯片被读保护了。STM32F103C8T6支持读保护，如果之前被人设过保护位，OpenOCD会报错。解决办法是用ST-Link Utility先解除保护，再回到PlatformIO下载。

5.4 工程文件版本管理的最佳实践

MDK5的工程文件是二进制格式的.uvprojx，Git diff基本看不出改了什么。PlatformIO的platformio.ini是纯文本，每次改动在Git里一目了然。我的做法是把.pio文件夹加入.gitignore，只提交platformio.ini、src、lib和include。这样别人克隆下来，装好PlatformIO一编译就能跑，不需要任何额外配置。

如果标准库文件太大不想提交，可以在README里写清楚下载地址和放置路径，或者用Git Submodule的方式引入。我一般直接把标准库提交进去，因为V3.5.0版本不会再变了，提交一次一劳永逸。

6. 常见问题速查与独家经验

6.1 编译下载问题排查表

6.2 我踩过的三个印象最深的坑

第一个坑是启动文件选错。我一开始用了startup_stm32f10x_hd.s，编译能过，下载也能跑，但中断向量表偏移不对，串口中断死活进不去。后来查数据手册才发现C8T6是中等容量，应该用md后缀。这个坑隐蔽在于编译不报错，只是功能不正常。

第二个坑是HSE_VALUE没改。我有一块板子焊的是12MHz晶振，但HSE_VALUE还是默认的8000000，结果系统时钟跑到了108MHz，串口波特率全乱。后来用示波器量了晶振频率才找到原因。所以拿到新板子第一件事就是确认晶振频率。

第三个坑是build_src_filter的路径写法。我一开始写的是+<lib/STM32F10x_StdPeriph_Driver/src/*.c>，编译一直报找不到文件。后来发现PlatformIO的源文件过滤是相对于src目录的，要写成+<../lib/...>。这个在官方文档里写得很隐晦，试了好几次才搞对。

6.3 提升开发效率的几个小技巧

第一个技巧是善用VSCode的代码片段。标准库的GPIO初始化代码很长，我把它做成snippet，输入gpioinit就能展开。具体做法是在VSCode里按Ctrl+Shift+P，输入"snippet"，选"配置用户代码片段"，然后编辑对应的JSON文件。

第二个技巧是用PlatformIO的串口监视器。点左下角的插头图标就能打开串口终端，不用再开额外的串口助手。波特率在platformio.ini里用monitor_speed = 115200配置。

第三个技巧是把常用的编译下载命令绑定到快捷键。VSCode的快捷键设置里搜索"PlatformIO"，可以给Build、Upload、Monitor分别绑定顺手的组合键。我绑的是F5编译、F6下载、F7开串口，效率提升明显。

6.4 关于国产替代芯片的兼容性说明

现在市面上有不少STM32F103C8T6的国产替代品，比如GD32、APM32、CH32等。这些芯片在引脚和寄存器层面做了兼容，但细节上有差异。用标准库开发时，大部分代码可以直接跑，但要注意几点：一是Flash编程算法可能不同，下载时如果报错，需要换对应的OpenOCD配置；二是某些外设的时序参数有差异，比如ADC采样时间；三是系统时钟配置，国产芯片的PLL锁定时间可能更长，需要加长超时等待。

我实测过GD32F103C8T6，用同样的标准库工程，改一下upload_protocol和Flash算法就能正常下载运行，GPIO和USART完全兼容，但ADC的精度和STM32有细微差别。如果你做的是对精度要求不高的项目，国产替代完全可用。

6.5 后续可以扩展的方向

这套环境搭好之后，你可以继续往上加东西。比如接入FreeRTOS，PlatformIO的库管理器里直接搜就能装，比MDK下手动移植方便得多。再比如用PlatformIO的单元测试功能，在PC上跑逻辑代码的测试，不用每次都下载到板子上。还可以配置CI/CD，每次提交代码自动编译，确保没有破坏构建。

我个人下一步打算把调试配置再优化一下，加上RTT打印，这样就不用占用串口了。RTT是SEGGER出的实时传输技术，通过SWD接口输出日志，速度比串口快得多，而且不占外设资源。J-Link支持得最好，ST-Link配合OpenOCD也能用，配置稍微麻烦一点，但值得折腾。