三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

30分钟搞定CH32开发环境：从MounRiver Studio安装到LED点灯实战

发布时间：2026/8/17 2:21:01 三亩地 编程学习日记
30分钟搞定CH32开发环境：从MounRiver Studio安装到LED点灯实战

1. 项目概述：从零开始，搞定CH32开发环境

最近几年，国产MCU的势头越来越猛，其中沁恒微电子的CH32系列凭借其出色的性价比和丰富的资源，在不少项目里都成了我的首选。无论是做个小巧的物联网终端，还是开发个需要USB或蓝牙功能的设备，CH32V103、CH32V307这些型号都能很好地胜任。但很多朋友拿到开发板或者芯片后，第一步就卡在了环境搭建上——官网资料在哪？该装哪个IDE？驱动怎么搞？这一堆问题确实让人头大。

我自己也是从这一步过来的，深知一个顺畅、稳定的开发环境是后续所有工作的基石。今天，我就把自己搭建CH32开发环境的完整流程、踩过的坑以及一些私藏的工具技巧，从头到尾梳理一遍。这篇文章的目标很明确：让你在30分钟内，从一台“干净”的电脑，到能够成功编译、下载并运行一个CH32的“点灯”程序。无论你是刚接触嵌入式的新手，还是从其他平台（比如STM32）转过来的老手，这份指南都能帮你快速上路。

2. 核心思路与工具链选型解析

搭建一个嵌入式开发环境，本质上是在配置一条从“源代码”到“芯片内部可执行二进制文件”的完整流水线。对于CH32系列（特别是基于RISC-V内核的CH32V系列），这条流水线主要包含几个关键环节：代码编辑与项目管理、编译器、调试下载器、以及芯片支持包。我们的工作就是为每个环节选择合适的工具，并把它们正确地连接起来。

2.1 为什么选择MounRiver Studio作为主IDE？

市面上支持RISC-V的IDE不少，比如官方的MounRiver Studio (MRS)、开源的PlatformIO、或者通用的Eclipse+插件。对于CH32的初学者和大多数项目开发者，我强烈推荐直接从官方的MounRiver Studio (MRS)开始。理由如下：

  1. 开箱即用，集成度高：MRS是沁恒官方基于Eclipse深度定制的IDE。它已经集成了GCC RISC-V编译器、OpenOCD调试服务器、以及CH32全系列芯片的芯片支持包（Device Family Pack, DFP）。你不需要自己去分别下载、配置、链接这些工具，安装完MRS，一个完整的基础开发环境就基本就绪了。这能避免大量因版本不匹配、路径配置错误导致的问题。
  2. 官方支持与兼容性保证：MRS的更新节奏与沁恒的芯片固件库、参考例程保持同步。新建工程时，你可以直接选择具体的芯片型号（如CH32V103C8T6），IDE会自动关联对应的启动文件、链接脚本和基础外设库，确保底层兼容性无误。
  3. 调试体验流畅：MRS内置的调试接口对沁恒自家的WCH-Link调试器做了深度优化。连接、下载、单步、查看外设寄存器，整个过程非常顺畅，几乎不需要额外配置。
  4. 降低学习成本：对于新手，在“如何让程序跑起来”这个阶段，应该把精力集中在代码逻辑和硬件原理上，而不是折腾构建系统。MRS提供了直观的图形化配置界面（类似STM32CubeMX的引脚配置、时钟树配置工具正在完善中），让入门更平滑。

当然，MRS并非没有缺点。它的界面基于Eclipse，对电脑性能有一定要求；对于追求极致轻量或深度定制构建流程的资深开发者，可能会觉得不够灵活。但对于“快速搭建环境并开始开发”这个首要目标，MRS是目前最稳妥、最高效的选择。等你熟悉了整个流程后，完全可以再探索PlatformIO或纯命令行编译的方式。

2.2 硬件调试器的选择：WCH-Link是首选

要把编译好的程序烧录到芯片里，并支持在线调试（设置断点、查看变量），你需要一个硬件调试器。对于CH32：

  • WCH-Link (或 WCH-LinkE)：这是沁恒官方的调试下载器，价格亲民，功能专一。它支持CH32全系列的SWD（串行调试）接口下载和调试。强烈建议购买一个。它有两种模式：通过跳线帽切换为“DAP-Link”模式或“RV-Link”模式。对于CH32V系列RISC-V内核，我们通常使用DAP-Link模式。
  • J-Link：如果你手头已经有SEGGER的J-Link，并且型号比较新（固件支持RISC-V），也可以使用。但需要在MRS中额外配置，且对于CH32F系列（ARM Cortex-M内核）支持更好。对于CH32V，使用WCH-Link更省心。
  • 串口ISP：仅用于程序下载，不支持调试。可以作为备用方案，但不推荐作为主要开发方式。

结论：准备一个WCH-Link（设置为DAP-Link模式），这是与MRS配合最默契的搭档。

3. 软件安装与配置全流程实操

接下来，我们进入一步步的实操环节。请严格按照顺序操作。

3.1 步骤一：获取所有必要的安装包和资料

在开始安装前，建议建立一个专门的文件夹，例如D:\CH32_Dev，用来存放所有安装包、资料和后续的工程。需要下载的核心资源如下：

  1. MounRiver Studio (MRS) 集成开发环境：

    • 去哪里下：访问沁恒微电子官方网站，找到“技术支持”或“下载中心”栏目。
    • 如何找：在下载中心搜索“MounRiver Studio”或直接查找CH32系列对应的开发工具。建议下载最新稳定版本。
    • 文件是什么：通常是一个名为MounRiver_Studio_Setup_Vxxx.exe的Windows安装程序（大小约几百MB）。

  2. CH32系列资料包（含标准外设库、例程）：

    • 同样在官网下载中心，查找“CH32Vxxx系列评估板资料”或“CH32标准外设库”。
    • 这个资料包通常是一个ZIP文件，解压后包含：
      • EVT(Evaluation Board Tools)：最重要的部分，内含Examples（针对各个外设的示例代码）、Libraries（芯片底层驱动库）、Startup（启动文件）、Projects（工程模板）。
      • Datasheet和Reference Manual芯片数据手册与参考手册（必备的硬件查询文档）。

  3. WCH-Link调试器驱动：

    • 如果你购买的是WCH-Link，通常卖家会提供驱动，或者驱动已集成在MRS安装包内。
    • 为了保险起见，可以去官网下载独立的“WCH-Link驱动”包。

注意：官网资料结构有时会更新。如果找不到，一个更直接的方法是：在沁恒官网找到某个具体型号评估板（如CH32V103评估板）的页面，该页面下的“相关资料”或“资源下载”通常包含了上述所有内容的集合包。下载这个评估板资料包是最全的。

3.2 步骤二：安装MounRiver Studio (MRS)

  1. 关闭所有杀毒软件（避免安装过程中文件被误拦截）。
  2. 双击下载好的MounRiver_Studio_Setup_Vxxx.exe。
  3. 安装过程基本就是“下一步”到底，但有几个关键点：
    • 安装路径：建议不要安装在C盘默认的Program Files下，因为该路径有时会有权限问题。可以修改为D:\MounRiver这样的自定义路径。请记住这个路径。
    • 创建桌面快捷方式：勾选上。
  4. 安装完成后，先不要急着运行软件。

3.3 步骤三：安装WCH-Link驱动

  1. 将WCH-Link通过USB线连接到电脑。此时电脑会识别到一个新设备。
  2. 如果系统没有自动安装驱动，或者提示驱动未成功，就需要手动安装。
  3. 找到你下载的独立驱动包，或者进入MRS的安装目录（例如D:\MounRiver\Drivers\wch），里面应该有驱动安装程序（如WCH-LinkSetup.exe）或inf文件。
  4. 运行驱动安装程序，或通过设备管理器手动更新驱动指向该文件夹。
  5. 驱动安装成功后，在设备管理器的“通用串行总线设备”或“libusb-win32 devices”下，应该能看到“WCH-Link”或“CMSIS-DAP”设备。

验证驱动是否成功：打开电脑的“设备管理器”，将WCH-Link拔掉再重新插入，观察对应设备端口是否出现和消失。如果正常，说明驱动OK。

3.4 步骤四：运行MRS并完成初始配置

  1. 双击桌面快捷方式启动MounRiver Studio。
  2. 首次启动会让你选择一个工作空间（Workspace）。这相当于你所有工程项目存放的“根目录”。强烈建议将其设置到之前创建的D:\CH32_Dev下的一个子文件夹，例如D:\CH32_Dev\Workspace。不要使用默认的C盘路径，避免重装系统后工程丢失。
  3. 进入主界面后，我们先进行一项关键配置：设置工具链路径（虽然MRS已集成，但确认一下有益无害）。
    • 点击菜单栏Window->Preferences。
    • 在左侧找到MounRiver->Toolchain或Build Tools。
    • 确认“GNU RISC-V Cross Compiler Path”指向的是MRS安装目录下的GNU RISC-V Embedded Toolchain路径（例如D:\MounRiver\Toolchain\RISC-V Embedded GCC）。通常安装后已自动配置好。

4. 创建第一个工程：点亮一颗LED

环境搭好了，我们来真刀真枪地创建一个最简单的工程，实现LED闪烁。这是嵌入式世界的“Hello World”。

4.1 基于官方例程创建工程（最稳妥的方法）

对于新手，我强烈不建议从完全空白的工程开始。最好的方法是复制并修改一个官方例程。

  1. 定位例程：解压你下载的评估板资料包（EVT）。进入EVT\EXAM目录，这里按子型号组织了所有例程。例如，对于CH32V103，找到EVT\EXAM\GPIO\GPIO_Toggle这个目录。这个例程的功能就是翻转GPIO引脚，非常适合用来点灯。
  2. 导入工程到MRS：
    • 在MRS菜单栏，选择File->Import...。
    • 在弹出的对话框中，展开General，选择Existing Projects into Workspace，点击Next。
    • 在Select root directory处，点击Browse...，导航到你刚刚找到的GPIO_Toggle文件夹。
    • 此时，MRS会自动在“Projects”列表中识别出这个工程，勾选它。
    • 关键一步：不要勾选“Copy projects into workspace”。我们直接链接到原目录，这样原例程不会被改动，方便我们随时对照。点击Finish。
  3. 修改工程以适应你的硬件：
    • 现在你的工程浏览器里应该有了GPIO_Toggle项目。展开User目录，打开main.c文件。
    • 你需要根据自己开发板的原理图，修改LED连接的引脚。假设你的板子上LED连接在PC13引脚（这是很多迷你开发板的常见连接）。
    • 找到main函数中的GPIO_Init函数调用，将其操作的引脚从例程中的（比如PA0）改为GPIO_Pin_13。
    • 找到while(1)循环里的GPIO_WriteBit函数，将其操作的引脚也改为GPIOC, GPIO_Pin_13。
    • 同时，在GPIO_Init函数上方，确保已经开启了GPIOC的时钟：RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOC, ENABLE);。
    • 修改后的核心代码段大致如下：
      // 开启GPIOC时钟 RCC_APB2PeriphClockCmd(RCC_APB2Periph_GPIOC, ENABLE); // 初始化PC13为推挽输出，速率50MHz GPIO_InitStructure.GPIO_Pin = GPIO_Pin_13; GPIO_InitStructure.GPIO_Mode = GPIO_Mode_Out_PP; GPIO_InitStructure.GPIO_Speed = GPIO_Speed_50MHz; GPIO_Init(GPIOC, &GPIO_InitStructure); while(1) { // PC13输出低电平，LED亮（假设低电平点亮） GPIO_WriteBit(GPIOC, GPIO_Pin_13, Bit_RESET); Delay_Ms(500); // 延时500ms // PC13输出高电平，LED灭 GPIO_WriteBit(GPIOC, GPIO_Pin_13, Bit_SET); Delay_Ms(500); }
    • 注意：LED是低电平点亮还是高电平点亮，取决于你的硬件电路。上述代码假设LED阳极接VCC，阴极接PC13（即低电平导通点亮）。请根据实际情况调整Bit_RESET和Bit_SET的顺序。

4.2 编译工程

  1. 在工程浏览器中，右键点击GPIO_Toggle项目，选择Build Project，或者点击工具栏上的“锤子”图标。
  2. 下方的“Console”控制台会输出编译信息。如果一切顺利，最后会看到类似这样的信息：
    Finished building target: GPIO_Toggle.hex Build Finished. 0 errors, 0 warnings.
    “0 errors, 0 warnings”是我们最想看到的。同时，在工程目录下会生成Objects文件夹，里面包含了可执行文件GPIO_Toggle.hex和GPIO_Toggle.bin。

4.3 硬件连接与下载调试

这是最后一步，也是最激动人心的一步。

  1. 硬件连接：

    • 确保开发板断电。
    • 将WCH-Link的SWD接口（通常标有SWCLK、SWDIO、GND）与开发板对应的调试接口连接。一般连接三根线：SWCLK、SWDIO、GND。
    • 将WCH-Link的USB口插入电脑。
    • 给开发板上电（可以通过USB供电或外部电源）。

  2. 配置MRS中的调试器：

    • 在MRS中，右键点击你的工程，选择Properties。
    • 在左侧找到C/C++ Build->Settings。
    • 在Tool Settings选项卡下，找到GNU RISC-V Cross C Linker->Miscellaneous。
    • 确保链接器脚本（Linker script）指向的是你所用芯片对应的.ld文件（通常位于Libraries\LdScript目录下）。导入的例程通常已配置好。
    • 更重要的是，找到MounRiver->Debug Hardware Config或直接在工具栏找到调试配置按钮。
    • 在调试配置对话框中，选择你的工程，在“Debugger”选项卡下：
      • Debugger Type: 选择CMSIS-DAP(对应WCH-Link的DAP模式)。
      • Interface: 选择SWD。
      • 其他参数通常保持默认即可（如速度、复位方式）。

  3. 下载与运行：

    • 点击工具栏上的“绿色虫子”图标旁边的下拉箭头，选择Debug As->MounRiver Hardware Debug。
    • 或者，直接点击“下载”图标（通常是一个向下的箭头），这会将程序烧录到芯片并复位运行。
    • 如果一切正常，你会看到控制台输出下载进度，最后显示“Program Finished”。你的开发板上的LED应该开始闪烁了！

  4. 进入调试模式：

    • 如果点击了“Debug”，MRS会切换到调试视角。你可以：
      • 点击“暂停”按钮暂停程序。
      • 按F5（Step Into）、F6（Step Over）进行单步调试。
      • 在“Variables”窗口查看变量值。
      • 在“Registers”窗口查看CPU和外设寄存器状态。
      • 点击“Resume”（F8）继续全速运行。
    • 要退出调试模式，点击调试视角的红色“停止”按钮，然后点击右上角的“C/C++”视角切换回编辑模式。

5. 常见问题与深度排坑指南

即使按照步骤操作，你也可能会遇到一些问题。这里我整理了最常见的一些“坑”及其解决方案。

5.1 编译问题

问题1：编译时提示“找不到头文件”或“undefined reference to xxx”。

  • 原因：这是最常见的编译错误，根本原因是工程路径配置错误。MRS没有找到.c源文件或.h头文件。
  • 排查步骤：
    1. 右键工程 ->Properties->C/C++ General->Paths and Symbols。
    2. 在Includes选项卡，检查“GNU C”和“GNU C++”的包含路径。必须包含以下关键路径（路径需根据你的实际存放位置调整）：
      • 芯片外设库头文件路径：你的EVT目录\Libraries\CH32V10x_StdPeriph_Driver\inc
      • 内核头文件路径：你的EVT目录\Libraries\Core
      • 启动文件路径：你的EVT目录\Startup
      • 用户代码路径：你的工程目录\User(通常已自动添加)
    3. 在Source Location选项卡，确保User、Libraries等文件夹被正确关联为源代码目录。
    4. 如果使用例程导入，通常路径是相对路径。如果移动了EVT目录，就会出错。此时最好重新导入，或手动修正所有路径。

问题2：编译通过，但生成的二进制文件特别大。

  • 原因：没有开启编译优化，或者调试信息占用了大量空间。
  • 解决：
    1. 右键工程 ->Properties->C/C++ Build->Settings->Tool Settings->GNU RISC-V Cross C Compiler->Optimization。
    2. 将Optimization Level从None (-O0)改为Optimize for size (-Os)。在开发调试阶段，可以用-Og（优化调试体验）；在发布时，务必使用-Os来减小体积。
    3. 在Debugging子选项下，可以取消Generate debug info (-g)来进一步减小体积（仅限发布版本）。

5.2 下载与调试问题

问题1：MRS无法识别到WCH-Link调试器（提示No CMSIS-DAP device found）。

  • 原因1：驱动未正确安装或冲突。
    • 解决：回到设备管理器，查看WCH-Link设备是否有黄色叹号。卸载驱动，重新插拔，使用MRS安装目录下的驱动重新安装。确保使用的是DAP模式的驱动。
  • 原因2：WCH-Link模式不对。
    • 解决：检查WCH-Link上的跳线帽。对于CH32V系列RISC-V调试，应设置为DAP模式（通常跳线帽连接DAP一侧的两个引脚）。具体请参考你的WCH-Link说明书。
  • 原因3：USB线或接口问题。
    • 解决：换一根可靠的USB数据线（能传输数据的），并尝试电脑上不同的USB接口（最好直接连接主板后置接口）。

问题2：能识别到调试器，但下载时失败（提示擦除/编程/校验失败）。

  • 原因1：芯片进入睡眠/待机模式，或者看门狗复位导致。
    • 解决：在下载配置中，修改复位方式。在调试配置的“Debugger”或“Startup”选项卡，将Reset Mode从Software System Reset改为Hardware Reset或Core Reset。硬件复位更可靠。
  • 原因2：芯片被写保护（读保护）。
    • 解决：这是一个比较麻烦的情况。可以尝试通过串口ISP方式，使用沁恒的ISP工具（在资料包EVT\TOOLS\ISP里）进行“全片擦除”，解除保护。操作时注意选择正确的串口号和波特率，并让芯片进入ISP模式（通常需要操作BOOT引脚）。
  • 原因3：目标板供电不足。
    • 解决：如果开发板功耗较大（连接了多个外设），仅靠WCH-Link的5V输出可能不够。尝试给开发板单独供电，并确保共地。

问题3：程序能下载，但运行不正常（LED不闪，或行为异常）。

  • 原因1：时钟配置错误。
    • 解决：检查system_ch32v10x.c（或其他型号对应的文件）中的SystemInit函数。确认系统时钟源（HSI/HSE）和主频是否配置正确。很多例程默认使用内部高速时钟（HSI），如果你的代码依赖外部晶振（HSE），而板子上没有焊接，就会出问题。最简单的测试方法是，在初始化代码里先使用默认的HSI时钟。
  • 原因2：延时函数不准确。
    • 解决：例程中的Delay_Ms函数通常是基于SysTick中断或简单循环实现的。如果系统时钟频率改了，这个延时函数的参数也需要调整。可以先用一个非常慢的闪烁（比如延时1秒）来测试。
  • 原因3：硬件连接错误。
    • 解决：万用表是你的好朋友。测量一下LED所在引脚在程序运行时的电压是否在高低电平之间跳变。如果没有，回头检查代码的GPIO配置；如果有，检查LED的限流电阻和连接方式。

5.3 环境与工程管理心得

  1. 资料备份：将下载的官方EVT资料包完整备份到网盘或其它安全位置。这是你的“源代码”，不要轻易修改原文件。所有工程都通过“导入”而非“复制”的方式创建。
  2. 工作空间整洁：在Workspace内，为不同项目建立清晰的文件夹。例如Workspace\Project_A,Workspace\Project_B。MRS的“导入工程”功能可以很好地管理分散在不同物理位置的工程。
  3. 善用“刷新”和“索引重建”：当你从外部向工程目录添加或删除文件后，在MRS工程浏览器中右键点击工程，选择Refresh。如果代码提示（Content Assist）出现问题，可以尝试Index->Rebuild。
  4. 版本控制：尽早使用Git。将User目录下你自己写的代码，以及工程配置文件（.project,.cproject）纳入版本管理。Libraries等官方库文件可以通过子模块（Submodule）或记录版本号的方式管理。

6. 进阶配置与效率提升技巧

当基础环境跑通后，你可以进一步优化开发体验。

6.1 配置代码编辑与美化

MRS基于Eclipse，支持丰富的插件和配置。

  • 代码格式化：在Window->Preferences->C/C++->Code Style中可以配置格式化规则。我习惯将缩进改为4个空格，大括号换行风格设为“Allman style”。可以导出配置供团队共享。
  • 代码模板：在Preferences->C/C++->Editor->Templates中，可以创建自定义代码片段。例如，创建一个名为fori的模板，内容为for(int i=0; i<${length}; i++){\n\t${cursor}\n}，这样输入fori再按快捷键就能快速生成循环框架。
  • 快捷键：熟悉常用快捷键，如Ctrl+/(注释/取消注释)，Ctrl+Shift+F(格式化)，Ctrl+O(快速大纲)，能极大提升编码效率。

6.2 使用串口打印调试信息

除了单步调试，串口打印是最常用的调试手段。

  1. 硬件连接：将开发板的UART TX引脚连接到USB转TTL模块的RX，RX接TX，GND互连。
  2. 代码实现：在工程中初始化一个UART外设（如USART1），重写fputc函数，将printf的输出重定向到串口。
    // 在包含stdio.h后，重写此函数 int fputc(int ch, FILE *f) { while(USART_GetFlagStatus(USART1, USART_FLAG_TC) == RESET); // 等待发送完成 USART_SendData(USART1, (uint8_t)ch); return ch; }
  3. PC端查看：使用串口助手软件（如MobaXterm、Putty、或者沁恒自带的串口调试助手），选择正确的COM口和波特率，即可看到printf输出的信息。

6.3 管理多个芯片型号的工程

如果你同时开发CH32V103和CH32V307的项目，为了避免库文件冲突，建议：

  • 为每个芯片系列建立独立的Workspace：比如D:\CH32_Dev\Workspace_V103和D:\CH32_Dev\Workspace_V307。
  • 使用符号链接管理公共库：如果觉得复制多份库文件占用空间，可以在每个Workspace内，使用Windows的“创建符号链接”功能（mklink /J命令），将实际的EVT库目录链接到工程中。但这需要一定的系统管理知识，新手慎用。

环境搭建本身不是目的，而是一个让你能专注于创造的过程。第一次成功点亮LED的那一刻，意味着通往CH32世界的大门已经为你敞开。后续无论是操作更复杂的外设，还是实现更精巧的逻辑，都建立在这个稳定可靠的基础之上。如果在搭建过程中遇到上面没覆盖到的问题，最好的方法是去沁恒的官方社区或相关技术论坛，用具体的错误信息搜索，你遇到的问题，很可能已经有前辈踩过坑并给出了解决方案。

编程学习 学习日记 实战经验
← 返回列表