必须手动配置VSCode工具链路径，因插件不自动发现riscv-none-elf-gcc等工具；compilerPath、miDebuggerPath等需精确填写绝对路径并匹配架构（如riscv32/riscv64），且须在终端验证命令可用性，否则导致编译失败、调试拒绝或IntelliSense失效。
必须手动配置工具链路径，VSCode不会自动发现riscv-none-elf-gcc或riscv64-unknown-elf-gdb。所有插件（C/C++、Cortex-Debug、CMake Tools）都依赖显式指定的compilerPath和miDebuggerPath，填错路径或用错架构变体（如混用riscv32与riscv64）会导致编译失败或调试连接拒绝。
确认工具链安装位置并验证命令可用性
在终端中运行以下命令，确保返回版本号而非“command not found”：
-
riscv-none-elf-gcc --version（常见于GD32VW553等32位RISC-V芯片） -
riscv64-unknown-elf-gcc --version（常见于QEMU模拟或64位SoC） -
riscv-none-embed-gdb --version或gdb-multiarch --version（调试器，注意后者需额外配置set architecture riscv:rv32） -
openocd --version（若用硬件调试）
Linux/macOS用户注意：如果用apt install安装（如gcc-riscv64-unknown-elf），二进制通常在/usr/bin/；若用源码编译安装，路径多为/opt/riscv/bin/或~/riscv-gnu-toolchain/install/bin/。Windows下MSYS2安装后路径类似C:\msys64\mingw64\bin\，但需确认实际存在riscv64-unknown-elf-gcc.exe文件。
c_cpp_properties.json里compilerPath必须精确匹配
这个文件控制IntelliSense补全和语法检查，填错会导致头文件标红、宏未定义、函数跳转失效。常见错误包括：
- 写成
"compilerPath": "riscv-none-elf-gcc"（没写绝对路径）→ VSCode无法定位 - 写成
"compilerPath": "/usr/bin/riscv64-unknown-elf-gcc"但实际安装的是riscv32-unknown-elf-gcc→ 编译报错target mismatch - Windows下路径含空格（如
C:\Program Files\...）未加引号或转义→ 配置加载失败
正确示例（Linux）："compilerPath": "/opt/riscv/bin/riscv32-unknown-elf-gcc"
对应defines应包含"__riscv_arch_test"或芯片型号宏（如"GD32VW553"），否则#ifdef __riscv__可能不生效。
launch.json中miDebuggerPath和debugServerPath不能共用一个路径
这是最常被忽略的分离点：GDB客户端和OpenOCD服务端是两个独立进程，路径必须分别指定。
-
miDebuggerPath→ 指向riscv-none-embed-gdb或gdb-multiarch可执行文件 -
debugServerPath→ 指向openocd可执行文件（不是.cfg文件！） -
debugServerArgs才传-f board/gd32vw553.cfg这类参数
若误将openocd路径填进miDebuggerPath，F5启动时会报错：Cannot launch program; not a valid executable。反过来，若debugServerPath填了GDB路径，则OpenOCD根本不会启动，调试器连不上localhost:3333。
tasks.json里make命令要带架构前缀
很多RISC-V项目（如Luban-Lite）使用make而非CMake，但默认make调用的是主机gcc。必须显式指定交叉工具链前缀：
- 错误写法：
"args": ["-j4"]→ 调用gcc，编译出x86可执行文件 - 正确写法：
"args": ["CROSS_COMPILE=riscv32-unknown-elf-", "-j4"]或通过环境变量"env": {"CROSS_COMPILE": "riscv32-unknown-elf-"}
更稳妥的做法是在tasks.json中直接调用make并传参，例如："args": ["CC=riscv32-unknown-elf-gcc", "LD=riscv32-unknown-elf-gcc", "-j4"]
否则即使c_cpp_properties.json配对了，编译产物仍是错的——调试时加载ELF会提示not in executable format。
真正麻烦的不是配多少字段，而是每个路径都得手工核对三次：终端能跑、JSON里写对、文件系统里真实存在。少一次验证，就卡在某个看似无关的报错上，比如Failed to launch GDB: spawn ENOENT——它根本不告诉你缺的是GDB还是OpenOCD，只说“找不到”。
