极客工场

Appearance

共 2,544 字预计阅读约 8 分钟

nextpnr 编码乱码报错速查：invalid UTF-8、BOM、全角符号与 locale ​

更新时间：2026-10-23。FAQ 速查页，面向在 Windows 上写 Verilog 和约束文件、再用 nextpnr（ice40 / ecp5 / nexus 各后端）做布局布线的同学。这类问题的共同特征是：报错行号指着一行看起来完全正常的代码，或者第一行 set_io 就解析失败，而「在记事本里打开明明没问题」是最常听到的辩解。nextpnr 本身按字节解析约束文件，前端的 Yosys 对非 UTF-8 字节更是直接拒绝，前端 Yosys 侧的同类排查见 Yosys 编码/乱码报错速查，语法解析类的整体框架见 nextpnr 语法/解析报错速查，Quartus 阵营对照见 Quartus 中文乱码与编码报错速查。

本文要回答的问题 ​

  • nextpnr 或 Yosys 报 invalid UTF-8 byte sequence，文件里到底哪里坏了？
  • set_io 约束文件第一行就 parse error，可第一行明明是对的，为什么？
  • 约束文件里的引脚名和代码里的端口名「看起来一模一样」，nextpnr 却说找不到，差在哪？
  • 终端里 nextpnr 输出的中文全乱码，LC_ALL 要不要设、设成什么？
  • 怎么确认一个 .v/.pcf/.lpf 文件是 GBK 还是 UTF-8、有没有 BOM、行尾是 CRLF 还是 LF？

一、报错原文与典型现象 ​

编码类问题的第一信号往往不是「乱码」两个字，而是一条和真实原因毫不相干的解析错。以下四类文案最典型，路径已占位：

1. Yosys 读源码时直接拒绝（GBK 中文注释）：

text
ERROR: `uart_rx.v' contains invalid UTF-8 byte sequences!
       Please fix your file encoding (e.g. using iconv).

2. nextpnr 读约束文件首行就报错（UTF-8 BOM 被拼进第一个 token）：

text
ERROR: syntax error, unexpected TOK_IDENTIFIER, expecting TOK_SET_IO at line 1 of pins.pcf
ERROR: failed to parse PCF file 'pins.pcf'

3. 引脚名对不上（全角字符或中文引脚名）：

text
WARNING: no constraint for port 'clk' in PCF file
ERROR: port 'led＿0' not found in design

4. locale 是 C 时终端输出乱码：

bash
# 日志里的中文路径/注释显示为 ?? 或 \xe4\xb8\xad 形式的转义

第一条分流判据：报错带文件名和行号、指向具体内容，就是「文件字节问题」，去查编码与行尾；报错是「找不到端口/信号」而两边名字看着一样，多半是「字符集问题」——全角字符、中文标点或不可见字节。 两类修法完全不同，顺序不能反。另一个容易误判的信号是「记事本打开正常」——记事本按系统区域设置猜编码，nextpnr/Yosys 按 UTF-8 解析字节，两者结论经常不一致，永远以工具报错为准。

二、现象到根因总览 ​

报错现象可能原因快速确认处置
Yosys 报 invalid UTF-8 byte sequences源码是 GBK/GB18030（Windows 编辑器默认 ANSI 存盘）file src/top.v 显示 ISO-8859 或非 UTF-8iconv -f GBK -t UTF-8 转码
PCF/LPF 第 1 行 parse error文件带 UTF-8 BOM（EF BB BF），BOM 拼进首个 tokenhead -c 3 pins.pcf | hexdump -C 看 ef bb bf去 BOM，另存 UTF-8 无 BOM
端口名「看着一样」却 not found约束里用了全角下划线 ＿、全角分号或中文引脚名grep -nP '[\x80-\xff]' pins.pcf 看高位字节全部改回半角 ASCII
报错行号指向正常行、附近有中文注释GBK 字节溢出到下一行，吃掉分号或引号同上 grep 列出含高位字节的行转码后重跑 yosys
Windows 编辑后 nextpnr 行为异常CRLF 行尾，PCF 解析对行尾敏感cat -A pins.pcf 看行尾 ^M$dos2unix 收敛为 LF
终端输出中文乱码、日志变问号进程 locale 是 C/POSIX，无法输出多字节字符locale 查 LANG/LC_ALLexport LC_ALL=C.UTF-8 或 en_US.UTF-8
Notepad++/记事本改完就炸存盘编码被切成「UTF-8-BOM」或「ANSI（GBK）」编辑器状态栏看编码，或 hexdump 看头部显式选「UTF-8 无 BOM」重存

三、按决策树排查 ​

排查主线只有一条：先按报错原文分流，再验文件字节，最后才动 locale。locale 只影响显示，永远修不好一个本身编码错误的文件。

fpga/ts-nextpnr-encoding-locale.md D2 示意图

读这张图抓住一次分流：红色入口是现象；蓝色第一个节点是分流动作——报文说字节非法或解析失败走「文件字节」支，报文说端口找不到而名字看着对走「字符集」支；两支汇入橙色修复，每步只做一类转换；绿色是重跑 yosys 与 nextpnr-ice40 --json out.json --pcf pins.pcf 全流程验证通过；紫色收尾是把编码纪律固化进编辑器配置，而不是记住这次手工怎么救回来的。

第一步，探测文件真实编码。 Linux/macOS 上三条命令把嫌疑钉死：

bash
file src/top.v pins.pcf                    # UTF-8 Unicode text 才是 UTF-8；ISO-8859 多半是 GBK
head -c 3 pins.pcf | hexdump -C            # 头三字节 ef bb bf 即 UTF-8 BOM
cat -A pins.pcf | head                     # 行尾出现 ^M$ 即 CRLF

file 报 ISO-8859 text 而内容本该有中文，基本就是 GBK 文件。Windows 上没有这些命令时，用 VS Code 或 Notepad++ 右下角状态栏直接看当前编码。快速定位「哪一行藏着非 ASCII 字节」：

bash
grep -nP '[\x80-\xff]' src/top.v pins.pcf | head   # 列出所有含高位字节的行

很多「parse error 指向正常行」的案件，用这条一扫就能发现报错行的上一行注释里藏着 GBK 中文，或者约束行尾跟了一个全角分号——人眼在等宽字体下几乎分不出 ; 和 ；，字节层面却天差地别。

第二步，GBK 转 UTF-8。 Windows 简体中文环境下「ANSI」保存就是 GBK，Yosys 的词法分析器遇到非 UTF-8 高位字节直接抛 invalid UTF-8；nextpnr 虽不强制校验源码（它读的是 Yosys 产物），但约束文件经 GBK 中文污染后同样解析失败。显式转码，先留底：

bash
iconv -f GBK -t UTF-8 src/top.gbk.v -o src/top.v

批量处理整个工程时不要原地覆盖，先转一份再编译验证：

bash
for f in src/*.v; do iconv -f GBK -t UTF-8 "$f" -o "$f.utf8" && mv "$f.utf8" "$f"; done

VS Code 的对应动作是右下角点编码 →「通过编码重新打开」选 GBK 确认中文显示正常 → 再「通过编码保存」为 UTF-8。注意顺序：必须先用正确编码「重新打开」再转存，直接转存会把已经乱码的字节固化成错误的 UTF-8。

第三步，去 BOM 并收敛行尾。 部分编辑器保存 UTF-8 时在文件头加 EF BB BF 三个字节，PCF 解析器把 BOM 当成第一行标识符的一部分，于是 set_io 首行神秘报错：

bash
sed -i '1s/^\xEF\xBB\xBF//' pins.pcf       # Linux；macOS 用 sed -i ''
dos2unix pins.pcf                          # 没有 dos2unix 时：sed -i 's/\r$//' pins.pcf

CRLF 的危害在 LPF 这类带续行的约束格式里更明显——行尾多出的 CR 会被拼进字段值，引脚定位串对不上封装库，报出指向无辜行的错误。

第四步，全角字符与中文引脚名清零。 从中文文档、聊天工具里复制约束内容是全角污染的最大来源：全角下划线 ＿、全角分号 ；、全角引号混进信号名后，人眼看不出区别，nextpnr 按字节比对就是两个名字。把约束文件里所有高位字节逐行过一遍，引脚名、端口名、参数值一律改回半角 ASCII：

bash
grep -nP '[\x{FF01}-\x{FF5E}\x{3000}-\x{303F}]' pins.pcf   # 列出全角字符所在行

最后才是 locale。 只有「文件编码正确、编译通过，但终端输出中文乱码」这一种情况归 locale 管，在封装脚本里写死：

bash
export LANG=C.UTF-8 LC_ALL=C.UTF-8

这只影响进程如何解释和输出多字节字符，修不好一个 GBK 文件本身，所以永远排在最后。还有一个反向场景：文件是合法 UTF-8，但你在 GBK 终端（某些 Windows SSH 客户端默认 GBK）里 cat 出来全是乱码。这时不要回头把文件转成 GBK——乱的是终端的解码，不是文件。把终端字符集切成 UTF-8，文件保持不动。

还有一类隐蔽案件值得单独提：Makefile 里用 find 或通配符收集源文件时，把某个编辑器自动生成的 .bak、.swp 备份文件也扫了进去，而那个备份恰好是 GBK 编码——主文件全部正常，报错却一直都在。遇到这种情况，把报错文件名和工程里的实际文件清单对一遍，先确认炸的到底是哪个文件，再回到上面的字节排查流程。

四、防复发 ​

  • 源文件三统一：.v/.sv/.pcf/.lpf/.sdc 一律 UTF-8、无 BOM、LF 换行；VS Code 里固化 files.encoding: utf8、files.eol: \n。
  • 约束与语句区只放 ASCII：端口名、引脚名、模块名一律英文半角；从中文资料复制约束行后先过一遍全角检查再提交。
  • 中文只许进注释，且先验证：注释里放中文前，先在最小工程上确认 yosys -p "read_verilog test.v" 不炸；团队协作时干脆约定注释也用英文。
  • 工程路径全英文：含中文的目录名在部分 Makefile/脚本组合里会引发二次编码问题，建工程第一天起目录名就只用 ASCII。
  • 跨平台传文件走二进制模式：SFTP/SCP/压缩包不选文本转换；从 Windows 拷工程到 Linux 后先跑一遍 dos2unix 再构建，是最便宜的保险。
  • 构建脚本写死 locale：LANG/LC_ALL 写进 Makefile 头部或 CI 封装，不靠交互 shell 的默认值，换机器、换账号行为一致。

一句话总结 ​

nextpnr 编码乱码报错先按报错原文分流：invalid UTF-8 或 parse error 归文件字节，用 file 和 hexdump 认出 GBK 与 UTF-8 BOM，再以 iconv 转成 UTF-8 无 BOM、dos2unix 收敛行尾；端口名找不到而「看着一样」归字符集，用 grep 揪出全角符号和中文引脚名改回半角；locale 只管终端显示、修不好文件本身。根治靠「UTF-8 无 BOM + LF + 约束与语句区纯 ASCII + 全英文路径」四条纪律写进编辑器配置，编码问题就从玄学变成常识。