nextpnr 约束文件解析报错（PCF/LPF parse error）速查

更新时间：2026-10-23。FAQ 速查页，面向 FPGA 入门阶段的同学。症状很典型：yosys 综合过了，nextpnr-ice40 --pcf top.pcf 一上来就抛 ERROR: PCF parse error: line 3，布局布线直接退出。本篇只回答一件事：nextpnr 读不下去你的约束文件时，怎么在十分钟内定位真正写错的那一行。

本文要回答的问题

PCF 报 parse error: line N 时，第 N 行是出错处还是发现处？
为什么把 Vivado 的 set_property PACKAGE_PIN 抄进 .pcf 会在第一行就炸？
LPF 的 LOCATE COMP 对大小写、引号有什么硬性要求？
行尾多分号、中文分号、用 // 写注释为什么都算语法错？
BOM、CRLF 这类看不见的东西怎么让解析器报错？

一、报错原文：先看 nextpnr 真实长什么样

nextpnr 在读取约束阶段就抛错，文案很朴素——只有文件、行号，没有 Expecting 清单：

text

ERROR: PCF parse error: line 3
ERROR: syntax error, unexpected IDENTIFIER, expecting TOK_SET_IO (top.pcf:5)
ERROR: LPF parse error: unexpected token at line 7

读这三行抓住两点：

line N 多半是「发现处」：解析器读到第 N 行的某个 token 才发现前面收不住，真病灶常在它本身或相邻行；
报错的文件名后缀决定语法体系：.pcf 走 iCE40 的 set_io 一行一条，.lpf 走 Lattice 的 LOCATE COMP ... SITE "xx" ;——两套语法互不兼容，串台必炸。

排查永远从第一条报错开始，修一条重跑一条。

二、排查决策树

先看报错落在哪种文件：PCF 先查「是不是写成了 XDC/SDC 风格」，LPF 先查关键字大小写与引号；两类都查行尾标点、注释符、总线下标写法，首行就炸的直接验 BOM 与 CRLF。

direction: down

entry: "nextpnr 约束文件解析报错\nPCF / LPF parse error"
judge: "报错文件是 PCF 还是 LPF？\nline N 的 token 是什么？"
style: "PCF 查语法串台：\nset_io 端口 引脚 一行一条\n不是 set_property PACKAGE_PIN"
kw: "LPF 查关键字：\nLOCATE COMP 大写\nSITE 值带双引号 句尾分号"
punct: "查标点与注释：\n行尾多分号 中文分号\nPCF 注释只认井号"
bus: "查引脚名写法：\ndata[0] 与 data_0\n以 yosys 输出的端口名为准"
enc: "查编码：\nfile 看 BOM/CRLF\ndos2unix 转换"
reverify: "重跑 nextpnr\n只认第一条报错"

entry -> judge
judge -> style: "PCF 且像 XDC/SDC"
judge -> kw: "LPF 且关键字可疑"
style -> punct: "风格改对仍报错"
kw -> punct
punct -> bus: "标点正常仍报错"
bus -> enc: "line 1 或满屏报错"
punct -> enc: "首行就炸"
enc -> reverify

entry.style: { fill: "#FDECEC"; stroke: "#D9534F" }
judge.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
style.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
kw.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
punct.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
bus.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
enc.style: { fill: "#FEF3E2"; stroke: "#E08A1E" }
reverify.style: { fill: "#E9F8F0"; stroke: "#2E9E6B" }

读这张图抓住「先分流、再验字符」：红色是报错入口，蓝色是逐层排查动作，橙色是编码层修复（dos2unix / 去 BOM），绿色是干净重跑。任何一层命中就只修那一层，不要同时改语法又改编码，否则修好了也不知道哪一刀生效。

三、病因处置速查表

报错现象	可能原因	处置
第一条就是 `parse error: line 1`，文件像 Vivado 约束	把 XDC/SDC 风格（`set_property PACKAGE_PIN` / `set_pin_location`）抄进了 .pcf	改写成 PCF 一行一条：`set_io led 95`
`unexpected TOK_IDENTIFIER` 在某行中间	PCF 里一条写了多个引脚、或行尾多分号/中文分号 `；`	一行一条；删多余分号；全角改半角
LPF 报 unexpected token 且关键字小写	LPF 关键字大小写敏感，`locate comp` 不识别	全部大写：`LOCATE COMP "clk" SITE "A8" ;`
LPF 报 token 错且 SITE 值裸奔	LPF 的引脚名、端口名必须带双引号	`SITE "A8"`、端口名 `"data[0]"` 都加引号
某行以 `//` 开头被判语法错	PCF 注释符只认 `#`，`//` 是 C 风格注释不合法	注释改成 `# 说明文字`
报找不到端口 `data[0]` 类错误（或解析阶段就炸）	总线下标写法与网表端口名不一致（data[0] vs data_0 vs data_0_）	以 `yosys -p "read_verilog top.v; dump"` 打印的端口名为准改写
line 1 满屏乱码式报错	文件带 UTF-8 BOM，解析器首 token 即失败	编辑器另存为「UTF-8 无 BOM」
行号看起来对不上、每行都偏	Windows 编辑器存了 CRLF 行尾	`dos2unix top.pcf` 或 `sed -i 's/\r$//' top.pcf`

四、逐条排查展开

第一步：确认写的是哪套语法。 PCF 的全部合法命令一只手数得过来，最常用就是 set_io，格式是「命令空格端口名空格引脚号」，一行一条，没有等号没有括号：

bash

# top.pcf 正确写法：一行一条 set_io
set_io clk 21
set_io reset_n 87
set_io led[0] 95
set_io led[1] 96
set_io --warn-no-port unused_pin 100

对照反面教材：从 Vivado 工程抄来的 set_property PACKAGE_PIN 95 [get_ports led]、set_input_delay 这类 SDC 命令在 PCF 里一个都不认识，解析器读到 set_property 就抛 parse error，而且报的行号往往是第 1 行。如果你的 .pcf 看起来像 Tcl 脚本，那不用往下查了，整份按 set_io 重写。

第二步：LPF 走另一套规则——大小写、引号、句尾分号全是硬要求。 Lattice 的 LPF 语法是 LOCATE COMP "端口名" SITE "引脚位" ;，四个要素缺一不可：

bash

# top.lpf 正确写法：关键字大写，名称与引脚加双引号，句尾分号
LOCATE COMP "clk"     SITE "A8" ;
LOCATE COMP "led[0]"  SITE "B3" ;
IOBUF PORT "clk" IO_TYPE=LVCMOS33 ;

高频踩坑：locate 小写不识别；SITE A8 不加引号报 unexpected token；句尾漏分号，错误会落到下一行——这和 Quartus「报错行是发现处」同理，line N 报错先回读第 N-1 行结尾。

第三步：标点与注释逐字符过一遍。 PCF 注释只认 #，写 // set led pin 会被当成命令开头直接炸；行尾多写一个分号、或者从聊天工具粘贴时混进了中文分号 ；，解析器都会在那个字符处抛错。编辑器开「显示不可见字符」，全角符号会显出异常宽度，一眼能看出来。

第四步：总线下标以网表为准。 约束里的端口名必须和 yosys 综合后网表里的名字逐字符一致。Verilog 顶层写 output [3:0] led，网表里是 led[0] 到 led[3]，PCF 就该写 set_io led[0] 95；但有些综合流程会把名字压成 led_0。拿不准时先跑一次：

bash

yosys -p "read_verilog top.v; synth_ice40; dump" 2>/dev/null | grep -E "^\\s+(input|output)"

把打印出的端口名原样抄进约束文件，比凭记忆猜省一小时。还有一个隐蔽变种：顶层端口在综合时被优化掉（比如信号全程没驱动负载），约束里还留着它的 set_io，nextpnr 会在后续阶段报「端口不存在」——这不属于语法错，但排查入口和本篇相同，先确认网表里这个名字还在不在。

第四步补充：频率约束别混进 PCF。 很多教程让你写 freq clk: 50，这不是 PCF 语法——PCF 只管引脚位置，不管时序。nextpnr 的频率约束走命令行参数 --freq 50 或 --json 里的 frequency 字段；把 freq 写进 .pcf 同样抛 parse error。排查时看到约束文件里出现时序类关键字（freq、delay、clock），整行删掉改用命令行传参。

第五步：看不见的东西——BOM 与 CRLF。 用 Windows 记事本存过的 .pcf 常带 UTF-8 BOM，文件头多出的三个字节会让解析器在 line 1 就失败；从 Windows 共享目录拷来的文件带 CRLF 行尾，行号统计错乱，报 line 5 实际病灶在 line 4。一行命令验明正身：

bash

file top.pcf
# "UTF-8 Unicode (with BOM) text, with CRLF line terminators" —— 两个都要清
dos2unix top.pcf          # 去 CRLF；多数版本同时去 BOM
sed -i '1s/^\xEF\xBB\xBF//' top.pcf   # 只去 BOM 时用这个

第六步：逐行二分定位。 报错文案太含糊时的兜底手段：把约束文件后半段整体注释掉（每行加 #），能过就说明病灶在被注释段里，逐段放回，报错重现的那一行就是真凶。这比肉眼通读一份上百行的 .pcf 快得多。

五、防复发

模板起步不手抄：新项目从同 FPGA 族的现成 .pcf/.lpf 模板改，不从其他厂商工程搬约束文件。
编辑器装语法高亮：VS Code 有 PCF/LPF 高亮插件，# 注释、关键字大小写、引号配对有颜色兜底。
约束进版本库，CI 先跑解析：CI 里加一步 nextpnr-ice40 --pcf top.pcf --json /dev/null 级别的干跑，语法错在提交时就拦下，不进布局布线。
Windows 与 Linux 混用时统一行尾：仓库加 .gitattributes 写 *.pcf text eol=lf、*.lpf text eol=lf，从根上断掉 CRLF。
端口名变更同步改约束：RTL 改了总线写法（led[3:0] 改成 led0..led3）时同一次提交里更新 .pcf，别留到下次编译才想起来。
约束文件命名带族后缀：同项目多块板子时，top-ice40.pcf 与 top-ecp5.lpf 分开命名，Makefile 里按 --hx8k / --um5g-45k 目标各选各的，避免拿错文件报一堆看不懂的错。
动手改前先跑一遍干跑：约束文件每次改动后先 nextpnr-ice40 --pcf top.pcf --package bg121 --json /dev/null 级别的最小命令验证解析能过，再进完整流程，把语法错的反馈环压到秒级。

这一篇在知识体系里的位置

本篇是 FPGA 排错速查簇的一员，处理「约束文件写错了，nextpnr 在读取阶段就退出」这一类问题。约束能读但引脚名对不上网表符号，见 nextpnr 未定义符号速查；同样的「解析阶段报错」方法论在综合器一侧，见 Yosys 语法解析报错速查与 Quartus 语法错误速查——三家报错文案不同，但「报错行是发现处、逐条修第一条、编码层最后查」的套路完全通用。

一句话总结

nextpnr 约束文件解析报错先看文件后缀分两套排查：PCF 只认 set_io 端口引脚 一行一条，写成 XDC/SDC 风格必在第一行炸；LPF 的 LOCATE COMP "..." SITE "..." ; 对关键字大写、双引号、句尾分号是硬要求；两类文件都要防行尾多分号、中文标点、// 注释误用与总线下标写法和网表对不上，line 1 就炸或行号错乱时先 file 查 BOM 和 CRLF 再 dos2unix，拿不准就逐行二分注释定位，修完重跑只认第一条报错。

入门

进阶

专家

nextpnr 约束文件解析报错（PCF/LPF parse error）速查 ​

本文要回答的问题 ​

一、报错原文：先看 nextpnr 真实长什么样 ​

二、排查决策树 ​

三、病因处置速查表 ​

四、逐条排查展开 ​

五、防复发 ​

这一篇在知识体系里的位置 ​

一句话总结 ​

nextpnr 约束文件解析报错（PCF/LPF parse error）速查

本文要回答的问题

一、报错原文：先看 nextpnr 真实长什么样

二、排查决策树

三、病因处置速查表

四、逐条排查展开

五、防复发

这一篇在知识体系里的位置

一句话总结