Windows下CH55xDuino编译报错sdcc.sh语法错误的解决

如果你最近在 Windows 上折腾 CH55xDuino大概率会撞见这样一行报错sdcc.sh: syntax error: unexpected (。我第一次看到时也懵了明明脚本是官方自带的怎么语法错误后来发现这根本不是代码写错而是 Windows 的换行符和 shell 环境在捣乱。这篇东西就把完整排查过程写出来顺便讲讲 CH55xDuino 在 Arduino IDE 里编译链路是怎么回事以及怎么彻底避免同类问题。适合刚入坑 CH55x 系列单片机、使用 Arduino IDE 且编译一直不过的朋友。1. 先把报错和背后的编译链路看明白1.1 CH55xDuino 到底是什么CH55x 是沁恒WCH推出的增强型 8051 内核微控制器系列典型型号有 CH551、CH552、CH553、CH554、CH558、CH559。它保留了 8051 的指令集又塞进了 USB 控制器、大容量 Flash、ADC、PWM 这些外设价格还非常便宜国内玩的人越来越多。CH55xDuino 是一个第三方 Arduino 核心目的很简单让你能像写 Arduino UNO 那样写 CH55x用到的多半是digitalWrite、analogRead、SerialUSB这些熟悉的 API底层再帮你映射到 8051 的寄存器上。CH55xDuino 跟普通 Arduino 板卡最大的区别在于编译器。AVR 板卡用的是 AVR-GCCESP 系列用的是 Xtensa/RISC-V 工具链而 CH55x 这类 8051 核心只能靠 SDCCSmall Device C Compiler来编译。SDCC 对老式 8051 架构支持比较深但它的命令行参数、头文件组织方式和 GCC 完全不是一个路子所以 CH55xDuino 这个核心包在 Arduino IDE 中做了一层包装把复杂的 SDCC 调用封装成一个一个的脚本命令。这个包装层就是sdcc.sh的来历。很多新手拿到报错后喜欢直接去搜索引擎复制错误文本但如果不理解 SDCC 脚本在编译流程里的位置往往只能乱试。所以我先带你把这条链路理顺。1.2 sdcc.sh 在编译流程里的位置Arduino IDE 编译程序时并不是直接把代码丢给 gcc 或 sdcc而是通过一个叫platforms.txt的配置文件来决定具体执行什么命令。platforms.txt里写了类似“把 .c 文件编译成 .o 文件”的 recipe其中会引用工具链路径并且很多核心包还会写一个包装脚本方便跨平台调用。CH55xDuino 的安装目录一般在 Arduino 的hardware或packages目录下里面能找到tools/sdcc相关的子目录sdcc.sh就在这里。这个脚本做的事情说简单也简单接收一堆参数比如源文件路径、输出文件路径、芯片型号、优化级别然后拼出完整的 SDCC 命令再执行。说复杂也复杂因为它内部往往会有条件判断、路径拼接、参数数组操作这些一旦在错误的 shell 环境下运行就会出现莫名其妙的语法错误。1.3 报错字面拆解为什么是 unexpected (Shell 在执行脚本时遇到syntax error: unexpected (意思是解析器在读到一个括号时无法把它放进当前语法结构里。比如你写一个条件判断少了一个;或者do括号就会变得孤立又比如脚本里用了数组语法arr(...)但当前解释器不识别再比如一行里出现了没有闭合的引号导致括号被当成普通 token。在 CH55xDuino 这个具体场景里最典型的问题出在 Windows 的换行符上。因为很多.sh文件在 Windows 下被编辑器保存成了 CRLF 格式也就是每一行结尾除了 LF\n还多了一个回车符 CR\r。Bash 会把 CR 当成行内容的一部分。假设脚本里有一行是if [ $(which sdcc) ! ]; then这一行行尾的\r会黏在或者;后面下一行开头如果接着括号或逻辑符号Bash 读到这个多余的 CR 就可能把这行和下一行拼接出一个奇怪的 token最终报unexpected (。所以看到这个报错先别怀疑 CH55xDuino 作者写错了代码优先怀疑环境。下面我会把排查过程一步步列出来。2. 排查思路从环境到文件一路扫雷2.1 先确认 shell 和执行环境第一种情况很常见你在 Windows 下用 Git Bash 或 MSYS2 终端但 Arduino IDE 内部执行脚本时可能用的是自己的 shell 环境。两个环境的行为不一样脚本在终端手动跑没问题在 IDE 里跑就报错。排查第一步打开一个终端进入sdcc.sh所在目录先看当前 shell 是什么。执行echo $SHELL bash --version | head -n 2 file sdcc.shfile命令能直接告诉你脚本换行符情况如果输出里带着with CRLF line terminators问题差不多就定位了。如果你没有file也可以用cat -A看特殊字符cat -A sdcc.sh | head -n 20正常 LF 行尾在cat -A里显示为$CRLF 行尾会显示为^M$。看到一堆^M$那基本可以确认是换行符问题。还要注意有些精简的嵌入式系统默认 shell 是dash而不是bash。如果你用sh sdcc.sh来执行而脚本里用了 Bash 特有的语法比如array(...)、${var,,}同样会报unexpected (。CH55xDuino 的脚本本身应该兼容 Bash但如果你手动在sh下跑也有可能触发。2.2 行尾符是头号嫌疑在 Linux 和 macOS 上sdcc.sh很少出问题因为文件基本都是 LF。但在 Windows 上只要你用记事本、某些自带编码转换的编辑器或者 Git 的autocrlf设置脚本就可能被改成 CRLF。Git 的设置里有一个很容易踩的坑core.autocrlftrue会把仓库里的 LF 在检出时自动转成 CRLF。如果你把 CH55xDuino 的源码 clone 下来然后又用 Git Bash 去执行里面的脚本脚本很可能已经被转换了。虽然 Git 会自动识别 Shell 脚本并尽量保留 LF但true模式下依然存在误判的可能。验证方法很简单就用上面的cat -A。如果确认是 CRLF也不要急着改全部文件先只处理编译相关的.sh脚本确认问题解决后再批量转换。2.3 检查脚本内容是否有 BOM 或特殊字符换行符之外BOM字节顺序标记也是一个隐性杀手。有些 Windows 编辑器在保存 UTF-8 文件时会自动加 BOM也就是文件开头多出EF BB BF三个字节。Bash 在执行脚本时会把 BOM 当成 shebang 的一部分比如#!/bin/bash会变成BOM#!/bin/bash导致解释器路径错误报错可能是bad interpreter或command not found。如果文件的 shebang 被污染后续解析也可能出现诡异的 syntax error。检查 BOM 可以用hexdump -C sdcc.sh | head -n 2看到开头有efbbbf就是有 BOM。清除 BOM 可以用sed -i 1s/^\xEF\xBB\xBF// sdcc.sh。如果拿不准直接在终端里重写一个干净版本最省事。还要留意脚本里是否有中文字符或全角符号。理论上正规项目不会犯这个错但如果你修改过脚本比如手工把某个中文注释粘贴进去编辑器编码不一致就可能在解析时产生意外字符最终报错位置也会莫名其妙指向某个括号。2.4 检查路径空格与括号Program Files 的隐藏大坑还有一种情况跟脚本本身无关而是执行环境变量里的路径带特殊字符。Windows 下 Arduino IDE 经常装在C:\Program Files (x86)\Arduino这个路径本身就带空格和括号。sdcc.sh 内部如果使用没有加引号的变量来拼接路径路径里的(就可能被 Shell 解析成子 shell 的语法标记。比如某个变量展开后是SDCC_PATHC:\Program Files (x86)\Arduino\hardware\...如果没有处理执行到$(...)或拼接命令时Shell 可能把(当作语法关键字从而导致unexpected (。排查方法在终端里执行echo $SDCC_PATH看看有没有括号或者运行脚本前临时把环境变量里带括号的路径加引号。这种问题最恶心的地方在于它时好时坏取决于脚本调用时的变量展开顺序。CH55xDuino 的官方脚本其实已经做了很多引号处理但如果你接的是自己改过的核心包或者用了很奇怪的工作目录就很容易碰到。2.5 用最小脚本复现并定位如果你不确定到底是换行符还是语法问题就做一个最小复现实验。在当前目录新建一个test.sh内容如下#!/bin/bash if [ $(echo ok) ok ]; then echo test passed fi先用 LF 保存运行bash test.sh应该能正常输出。然后把文件转成 CRLF再运行bash test.sh大概率会看到syntax error near unexpected token (或类似报错。这样就可以把罪魁祸首锁死在换行符上。如果这个最小实验在 LF 下也报错说明你的 Bash 环境有问题比如 Git Bash 没有正确安装、用户目录下有奇怪的bash_profile等。这时就要回到 2.1重新检查 shell 环境。3. 四种解决办法实测记录3.1 方案一用 dos2unix 转换脚本行尾确认了 CRLF 之后最直接的解决办法是统一改成 LF。Git Bash 里一般自带dos2unix如果找不到可以用sed处理sed -i s/\r$// sdcc.sh或者用 Perlperl -pi -e s/\r$// sdcc.sh运行后再次cat -A sdcc.sh | head -n 10确认没有^M$然后再回到 Arduino IDE 编译。如果之前已经编译到一半报错最好先点一下“项目 - 清理”再重新编译避免旧的临时文件干扰。我实际操作中发现CH55xDuino 的tools目录下不止一个.sh文件只转一个可能不够。你可以直接对整个tools目录扫一遍find . -name *.sh -exec sed -i s/\r$// {} 这个命令在 Git Bash 下很好用。转换完之后sdcc.sh: syntax error: unexpected (这个报错应该就消失了。3.2 方案二在 platforms.txt 里显式指定 bash 执行如果你的系统本身有多个 shell或者 Arduino IDE 调用脚本时自动用了sh而不是bash即使行尾符改对了某些语法在sh下也可能不兼容。这时可以在platforms.txt的编译 recipe 里强制用bash执行脚本。在 Windows 上CH55xDuino 核心包里的编译命令常常是直接写成{runtime.tools.sdcc.path}/sdcc.sh也就是说系统会用默认的 sh 去执行它。如果默认 sh 是 dash 或是一个不完整的 MSYS2 shell就很容易在解析括号时出问题。把 recipe 改成recipe.c.o.pattern... bash {runtime.tools.sdcc.path}/sdcc.sh ...保存后重启 Arduino IDE再编译一次。这个方案治本缺点是升级 CH55xDuino 时改动会被覆盖需要记住这个修改点。如果你有多个版本的 CH55xDuino也要一个个改过去。3.3 方案三写一个 Windows 批处理包装器绕开 Bash 脚本如果你是在纯 Windows 环境里、用的 Arduino IDE 也是 Windows 版其实还可以把sdcc.sh调用替换成sdcc.cmd。原理很简单Windows 批处理文件由cmd.exe执行不依赖 Bash因此不会受换行符和syntax error: unexpected (影响。具体做法是在sdcc.sh同目录下新建一个sdcc.cmd内容大致是把原脚本里的 SDCC 命令行调用参数原样搬过去。这个工作听起来麻烦其实大多数人的项目里 SDCC 调用参数并不复杂无非是sdcc -mmcs51 --xram-size ...加上一堆源文件路径。你可以在 Arduino IDE 的“文件 - 首选项 - 编译时显示详细输出”打开后看完整编译日志里那一长串sdcc命令把它复制进sdcc.cmd再把platforms.txt里的调用指向.cmd。这个方法我一般不作第一推荐因为需要复制的内容太多而且不同项目代码里宏定义、头文件路径都不一样。但如果你实在不想碰 Bash 脚本这是一个可以兜底的办法。3.4 方案四手动运行编译命令绕过 IDE 封装有时候你并不需要纠结sdcc.sh因为 Arduino IDE 的封装脚本只是用来拼命令的。你完全可以在终端里手动调用 SDCC 完成编译先把链路跑通再回头解决 IDE 集成的问题。做法是打开 Arduino IDE 的“编译时显示详细输出”随便编译一次虽然最后报错了但日志里会把 SDCC 的完整命令打印出来。你把这些命令复制到终端手动执行注意把路径引号处理好。如果手动执行成功说明 SDCC 本身没问题问题出在脚本环境如果手动执行也失败那就是 SDCC 工具链损坏或者路径不对。我自己更喜欢用这个办法因为能一眼看出 SDCC 是不是真的在工作。很多情况下真正卡住你项目的可能不是syntax error而是 SDCC 找不到头文件这类更底层的问题脚本报错只是把它挡住了。手动执行时这些真实错误会直接暴露出来。4. 验证、烧录和日常避坑4.1 编译通过后的判断方法修好脚本后重新编译留意底部信息栏。如果显示“编译完成”或者生成了.hex文件说明脚本已经正常工作了。在 Windows 上默认编译输出目录在C:\Users\你的用户名\AppData\Local\Temp\arduino...或项目目录的build文件夹里找到一个.hex文件确认它的修改时间是刚刚。接下来用 WCH 的烧录工具比如 WCHISPTool把 hex 烧录到 CH55x 芯片。CH55x 一般需要先进入 boot 模式很多板子需要按住下载键再上电具体看你的开发板定义。烧录成功后会显示芯片型号和 Flash 大小如果这里能通过说明编译产物是完好的。4.2 Windows 下 CH55x 使用的其他常见坑编译环境修好只是一个开始实际用 CH55x 做项目时还有几个高频坑。第一驱动问题。Windows 上 CH55x 的 USB 驱动偶尔会装不上表现为设备管理器里认不出设备。这时需要手动指定驱动路径一般可以在下载的 CH55xDuino 包目录里找到驱动文件或者从 WCH 官网获取。装完驱动后拔插一下 USB再试。第二串口监视器。CH55x 的SerialUSB和原生 Arduino 的串口不一样它走的是 USB CDC 虚拟串口有时 Arduino IDE 的串口监视器打不开说端口被占用。判断方法很简单先关掉所有占用该串口的软件再重试。第三boot 模式时序。烧录时如果一直提示找不到设备检查你是不是先按了下载键再上电有些板子做的是自动下载电路有些则是手动切换时序反了就只能重新尝试。4.3 常见问题速查表下面这张表是我在实际调试中整理出来的按报错现象分类方便你快速对照。报错现象最可能的原因推荐解决方式sdcc.sh: syntax error: unexpected (CRLF 行尾符 / shell 类型不对转换sdcc.sh为 LF或在platforms.txt强制用bash/bin/bash^M: bad interpreter脚本 shebang 带 CR 或 BOMsed -i s/\r$// sdcc.sh去除 BOMfile not found: sdccSDCC 工具链路径错误或未安装检查tools/sdcc目录确认 PATH 设置sdcc: command not found终端环境没有把 SDCC 加入 PATH手动执行脚本或把 SDCC 路径加入环境变量编译日志正常但一直卡住杀毒软件拦截临时文件关闭实时扫描或将 build 目录加入白名单这张表不用背遇到问题时对着查就行。很多时候问题不一定是单一个原因有可能是换行符和路径问题同时存在所以优先按表里的顺序排查。4.4 顺手再说点后续扩展从编译环境到实际项目编译问题解决后你可以开始正常的 CH55x 开发了。我当时就是拿 CH55x 做了一个迷你舵机控制器类似智能小车上的转向舵机模块。这里给一个小提醒CH55x 的 PWM 频率和 Arduino UNO 不一样直接用analogWrite的话舵机可能转不到预期角度。建议先查数据手册确认定时器时钟或者使用 CH55xDuino 官方例程里给出的 PWM 初始化方式。另外如果你用的是 Arduino IDE 2.x它内部集成的 builder 和 1.8.x 有一些差异偶尔会出现 1.8 正常编译、2.x 报错的情况。要是你也遇到这种“灵异事件”别急着换板子先检查一下核心包版本和platforms.txt是否一致很多时候就是新旧 recipe 混用导致的。我个人在实际操作中养成了一个习惯装完 CH55xDuino 后第一件事不是写代码而是把tools目录下所有.sh文件统一转成 LF。这样能避开九成以上的脚本报错。如果你也卡在这个报错上照着上面的步骤先试大概率一次就能过。