如果你和我一样手头攒了一抽屉CH552、CH551这种小板子想蹭Arduino的生态又实在不想回到Keil那套老旧的界面那CH55xDuino几乎是绕不开的选择。它把增强型8051内核的CH55x系列芯片包装成了Arduino开发板编译后端默认是SDCC编译器。这套组合在Windows上有一个很经典的下马威第一次点下编译按钮进度条还没走两步控制台就甩出一行sdcc.sh: syntax error: unexpected (然后整个编译流程直接中断。这篇文章我就围绕这个报错把它的背景、成因、完整排查链路、修复操作和防复发手段全部摊开讲。如果你的报错一模一样直接跳到第3节看修复命令如果你想搞明白为什么会在Windows上冒出这样一个像外星代码的shell语法错误建议从第1节顺序读下去后面每一个步骤我都给了能直接照抄的命令。1. 先复盘这个报错出现的完整背景1.1 CH55xDuino 和 sdcc.sh 到底是什么关系CH55x系列是8位增强型8051内核芯片而Arduino官方工具链默认是给AVR系列写的里面的avr-gcc根本不认识8051的指令集。所以CH55xDuino这个第三方核心包做了两件事第一把Arduino的API精简移植到CH55x上第二引入SDCCSmall Device C Compiler作为真正的编译驱动。SDCC本身是一个多平台开源的C编译器但在Windows上它并没有被包装得那么“Windows化”。CH55xDuino的作者在hardware/ch55x/tools/目录里放了一个sdcc.sh脚本让Arduino在编译时通过这个脚本来做路径定位、参数拼接最终再调用SDCC真正的编译程序。你可以把sdcc.sh理解成编译流水线上的扳道工。它不是编译核心但少了它整列火车就是开不到目的地。Arduino每次编译CH55x的工程都会先在platform.txt里找到编译recipe然后启动一个shell去执行sdcc.sh这个脚本再根据当前系统判断SDCC的可执行文件在哪、该传哪些参数。在Linux和macOS上这套流程很顺畅因为系统本身自带shell。但在Windows上shell这个东西是额外装的一旦执行环境或者脚本文件格式出了问题就会炸出你看到的那个语法错误。1.2 我的复现环境与触发步骤复现这个报错不需要什么特殊条件。我当时的环境是Windows 11Arduino IDE 2.3.x板卡选的CH552CH55xDuino是用git clone方式装进用户目录的git clone https://github.com/DeqingSun/CH55xDuino.git然后把整个CH55xDuino目录放到%LOCALAPPDATA%\Arduino15\packages\CH55xDuino\hardware\ch55x或在sketchbook的hardware目录下建立一个ch55x同名目录。打开Arduino IDE在开发板管理器里看到CH55x系列选项后选一块CH552把Blink样例编译一下大约两三秒后Arduino IDE的编译输出窗口就开始刷出一长串日志然后最显眼的位置出现了这行报错Forking /bin/sh -c C:\Users\xxx\AppData\Local\Arduino15\packages\CH55xDuino\hardware\ch55x/tools/sdcc.sh chip sdcc.sh: syntax error: unexpected ( exit status 1 Error during build: exit status 1exit status 1是Arduino把shell进程的退出码原样抛了出来真正要命的是sdcc.sh: syntax error: unexpected (这一行它来自shell解释器说明shell在解析sdcc.sh文件内容的时候就挂了根本没走到编译那一步。2. 核心问题sdcc.sh 为什么会触发 syntax error2.1 从编译日志看 sdcc.sh 的调用上下文Arduino在调用外部编译工具时不是直接执行sdcc.sh文件而是执行类似下面这样一条完整命令C:\Program Files\Git\bin\sh.exe -c C:\Users\xxx\AppData\Local\Arduino15\packages\CH55xDuino\hardware\ch55x/tools/sdcc.sh chip注意这里的关键信息是sh.exe去解析并执行sdcc.sh不是cmd.exe。也就是说你的机器上一定要有一个可用的sh类解释器Arduino才能完成这个调用。大多数情况下这个解释器来自Git for Windows也可能是MSYS2或者WSL。报错里的unexpected (来自shell的语法解析器。bash/sh这类shell在读取脚本时会按自己的语法规则逐行解析如果遇到某个token出现在它预期之外的位置就会抛syntax error。小括号(在shell里有特定含义要么是子shell的边界要么是函数定义的参数列表起始符要么是数组或命令替换的特殊语法。如果出现在不该出现的地方解释器就直接说看不懂拒绝继续执行。2.2 引发 unexpected ( 的最常见根因在Windows环境下第一个要怀疑的就是脚本的换行符。GitHub上CH55xDuino仓库里的所有.sh文件本来都是Unix风格的LF换行但Windows用户git clone时如果git全局配置了core.autocrlftruegit会自动把这些文件在checkout时全部改成CRLF换行也就是Windows记事本最常写的那个格式。问题在于shell解释器不认识CRLF里的那个\r回车符。一个正常的脚本行末尾应该只有一个\nCRLF版本会变成\r\nshell读到\r时会把它当成某个命令或参数的一部分。比如脚本里有这么一行CC$(dirname $0)/sdcc/bin/sdcc如果是CRLF这行实际解析出来是CC$(dirname $0)/sdcc/bin/sdcc\rshell在处理\r的时候会被它误导常见表现就是某些括号、引号状态判定错乱最终在语法解析阶段就报出unexpected (。第二个根因是脚本自带BOM头。如果某个工具或编辑器把脚本存成了UTF-8 with BOMBOM字符会出现在第一行的#!/bin/sh前面。shell看到#!时本来认得这行是指定解释器的但前面多了一个不可见字符这个识别就会失效连锁反应可能报出各种怪异的语法错误。第三个可能性是脚本本身用了bash特有语法而执行它的sh解释器其实是dash。这个在纯Windows下相对少见但不是没有有些精简的shell环境对括号、[[ ]]等语法支持不完整。CH55xDuino官方脚本用的是POSIX兼容写法正常情况下不会踩这个坑但如果你的副本被改动过就要注意。2.3 先拿到三份证据再动手修复之前我们要在Git Bash或者WSL里先确认问题到底出在哪别一上来就乱改。我用这些命令做了检查cd 你的ch55x/hardware/ch55x/tools目录 file sdcc.sh head -c 16 sdcc.sh | od -A x -t x1z sed -n 1p sdcc.sh | cat -Afile命令会直接告诉你文件的换行风格。如果输出里包含with CRLF line terminators那基本就是它了。od命令用来看文件开头的字节如果开头是efbbbf说明带着UTF-8 BOM。cat -A会把行尾的回车符显示成^M$一目了然。这三份证据能帮你精确区分是CRLF的问题还是BOM的问题又或者是脚本第一行被改坏的问题。下面第3节的四个方案就是按照证据导向来的。3. 从最可能到最隐蔽四种排查与修复方案3.1 方案一用 sed 一次性修复换行符如果确认是CRLF直接对sdcc.sh做一次换行符归一化就可以了。在Git Bash里执行sed -i s/\r$// sdcc.sh这个命令的作用是把每一行行尾的\r字符删掉保留\n。如果你手头有dos2unix这个工具也可以一步到位dos2unix sdcc.sh但更实用的建议是不要只修这一个文件。CH55xDuino包里可能还有其他.sh脚本虽然触发报错的是sdcc.sh但同一套CRLF转换是均匀作用在每个文件上的今天我帮你修好了sdcc.sh改天它还可能去执行另外的脚本然后继续炸。我直接把整个tools目录下的所有.sh文件统一修复find . -name *.sh -exec sed -i s/\r$// {} \;这条命令会递归查找当前目录下所有.sh文件把它们全部切掉CR。执行完以后再用file sdcc.sh确认输出变成了ASCII text没有再跟CRLF字样然后回到Arduino IDE重新编译。3.2 方案二清掉BOM和首行的隐藏字符如果你检查下来发现换行符本身没问题但head -c 16 sdcc.sh | od里看见了efbbbf那就要处理BOM。这个情况多半是有人在Windows上用记事本或某个国产编辑器打开脚本后另存为“UTF-8 BOM”格式造成的。清除BOM的命令是sed -i 1s/^\xEF\xBB\xBF// sdcc.sh它只对第一行做处理把开头的efbbbf三个字节删掉。处理后再用od确认开头已经是正常的23 21也就是ASCII字符#!。BOM问题比较阴险因为你在GUI编辑器里看起来脚本完全正常但shell解析就是不行。我见过有人为这个问题重装了三次CH55xDuino最后发现是编辑器自动加了BOM。3.3 方案三确认Arduino到底用的是哪个sh这个报错能出现说明Arduino至少找到了一个sh解释器。但如果你机器里同时装了多个shell环境比如WSL、Git Bash、MSYS2Arduino到底拿哪个来跑脚本有时候并不直观。可以在Git Bash里执行where sh where bash看看系统PATH里Shell的实际路径。我用的是Git for Windows自带的sh路径在C:\Program Files\Git\bin\sh.exe。如果你把sh.exe放到了一个带中文空格或括号的路径下那么Arduino生成命令行时拼接出来的引号可能有别扭也会造成奇怪的syntax error虽然这个概率比CRLF低不少。如果where sh什么也没找到说明你的机器上压根没有sh。这时候Arduino的报错通常会变成Cannot run program sh但既然已经出现了syntax error字样说明sh是存在的那就重点怀疑脚本格式而不是环境。3.4 方案四彻底重装核心包绕开手工clone如果你不想折腾脚本内容最干净的办法是放弃git clone的安装方式改用Arduino官方开发板管理器来装CH55xDuino。先在Arduino IDE里配置额外的板卡索引地址填上CH55xDuino发布页里那个package_ch55xduino_index.json地址然后在开发板管理器里搜索ch55x一键安装。这种安装方式从发布包直接下载zipzip里的文件不会像git clone那样按你的git配置做自动换行转换所以几乎不会出现CRLF问题。用arduino-cli的话也是一回事arduino-cli core update-index --additional-urls https://.../package_ch55xduino_index.json arduino-cli core install ch55xduino:ch55x如果你对网络环境有顾虑也可以手动下载对应的release zip解压后放到hardware目录。这样既保留了离线安装的确定性又绕开了git的换行污染是我现在比较推荐的安装路径。4. 修复之后的验证与烧录实战4.1 用 arduino-cli 做一次干净的编译验证修好脚本后别急着回IDE点按钮我建议先用arduino-cli做一次静默编译日志更干净也更容易判断是真修好了还是运气好绕过去了。先把arduino-cli装好然后找到你刚才编译失败的样例目录执行arduino-cli compile --fqbn ch55xduino:ch55x:ch552 你的样例目录FQBN里的ch552要根据实际板子改成ch551、ch554或ch559。如果一切正常日志末尾会出现编译生成的文件路径并且有类似Compilation successful的提示。用命令行编译还有个额外好处它不依赖IDE的GUI缓存可以避免Arduino IDE里那些偶尔出现的“伪报错”。我当时修完整包后跑一次编译还顺手把每个.sh文件都用file扫了一遍确保没有漏网之鱼。偶尔会有一种情况核心脚本是LF了但IDE的编译缓存还保留着旧的错误状态这时候重启Arduino IDE再试基本就稳定了。4.2 成功之后烧录环节的几个雷区编译通过只是第一步。把编译好的hex烧进CH552时还要先搞清楚板子处于什么状态。CH55x在出厂时通常带一个USB bootloader烧录需要让芯片在启动时进入bootloader模式。不同的板子进入方式不一样有的是按住DOWNLOAD键再插USB有的是把P3.1引脚拉低再上电具体看你的板子设计。CH55xDuino配套的烧录脚本通常叫wchisp它是通过USB直接和芯片的bootloader通信的不需要额外的USBASP硬件。烧录命令大致是这样wchisp flash -f 你的固件.hex如果上传失败先别骂编译器。看看系统设备管理器里CH55x有没有正确枚举成一个COM口或者USB设备很多时候其实是驱动没装好或者bootloader被以前的测试程序覆盖了。另外CH552这种芯片内部的闪存不大如果你在Arduino里打开了过多的库和字符串常量编译出的hex常常超过容量烧录工具会报错这属于正常的资源限制。还有一个我在实操中经常踩的坑CH55xDuino在Windows上若是用板载USB串口进行烧录容易被系统里其他串口工具占用。烧录前先关掉串口监视器和其他占用串口的软件否则wchisp会一直提示打不开设备看起来很像编译或烧录配置有问题。5. 如何在未来彻底避开这类问题5.1 Git的autocrlf才是真正的源头这次遇到syntax error根子上是git的换行符自动转换。很多Windows用户的全局git配置是core.autocrlftrue这个配置的本意是好的它在checkout时把仓库里的LF转成CRLF让Windows记事本打开文本文件时更友善在提交时再转回LF避免仓库被CRLF污染。但问题恰恰出在这个“本意”上。.sh脚本是给Unix shell执行的它对CRLF零容忍。git不知道这个文件是脚本它只知道“这是个文本文件帮你转成Windows风格吧”于是就把sdcc.sh转成了CRLF然后shell炸了。所以我建议把全局配置改成false一劳永逸git config --global core.autocrlf false git config --global core.safecrlf truecore.safecrlf的作用是git在做可能引起混乱的换行转换时给出警告相当于多了一层保险。改完配置后之前已经clone下来的CH55xDuino还需要重新拉一遍才能恢复LF文件最省事的办法是删掉重新clone。5.2 给仓库加 .gitattributes 做强制约束如果CH55xDuino仓库里原本就写了.gitattributes我在Windows上clone的时候就不会碰到这个坑了。这个文件的内容很简单* textauto *.sh text eollf它的意思是所有文本文件按自动规则处理但所有的.sh文件强制使用LF换行。有了这个声明不管用户本地的git配置怎么折腾checkout出来的.sh文件始终是LFshell再也不会被\r搞糊涂。这个文件对项目作者来说是治本的良药对我这种下游用户来说能做的是在clone下来后顺手检查一下仓库里是否已经带了.gitattributes。如果作者没有加你可以自己在本地手动加一个放在仓库根目录至少能防止后续的git操作再次破坏这些脚本。在团队协作或者多人维护的场景里.gitattributes比在群里吼“大家把换行符改成LF”有效得多。因为它是git层面的规则每个成员clone出来就已经是正确格式了。5.3 两个值得长期坚持的小习惯第一个习惯是修改任何.sh脚本之前先执行file 脚本名确认文件是LF还是CRLF。很多人在调试脚本时习惯在Windows上用一个带自动换行转换的文本编辑器打开文件改完保存问题就回来了。改shell脚本宁可编辑后明文检查一遍也不要让编辑器帮你做“人性化”的换行处理。第二个习惯是固定用一种安装路径。我见过最多反复报错的人都是这次用board manager装下次为了更新又用git clone装两边版本一混目录结构对不上脚本也被各种姿势改过。CH55xDuino这类第三方核心包我现在的习惯是只用release zip手动解压不用git clone因为zip里的换行符是发布者当时提交的状态不会被本机配置二次改写。如果你已经用了git clone方式并且已经触发过一次语法错误那修完这次之后最好把这个目录加入你日常编译环境里的“只读区域”不要顺手把整个hardware目录交给dropbox、坚果云这类云同步工具。云同步在后台对文件的复制和恢复有时候会把换行符搞回去这种环境下出现的诡异报错往往比今天这个更难排查。我的CH55xDuino核心包现在放在本地固定目录不参与任何云同步这半年再没碰见过syntax error: unexpected (这种问题。