Quartus 找不到文件/路径：Can't find file 与 File does not exist 速查

更新时间：2026-10-23。FAQ 速查页，面向用 Quartus Prime（含 Lite/Standard/Pro）做 FPGA 开发、工程在多台机器或多人之间拷贝的同学。典型场景：工程从同事那边拷来一打开，Project Navigator 的 Files 页一排红叉，编译直接断在「找不到文件」。文件明明就在目录里躺着，Quartus 却坚持说它不存在——这类「薛定谔的源文件」十有八九不是文件丢了，而是 .qsf 里记的路径字符串解析出来的位置，和文件实际所在的位置不是同一个。本篇只收「文件系统层面打不开」一族；文件在、编译器却看不见模块定义的（Error 10170 类），见 Quartus 找不到模块速查。同族问题在 Vivado 侧的对应写法见 Vivado 路径/文件不存在速查。

本文要回答的问题

• Quartus 的 Can't find file / File does not exist 报错原文长什么样，各对应哪个阶段？
• .qsf 里的相对路径到底相对谁？为什么换台机器、换个目录就全红？
• Windows 拷到 Linux（或反过来）后路径为什么失效，大小写怎么查？
• SEARCH_PATH、IP 生成目录、特殊字符各是什么坑，怎么用 Tcl 命令快速定位？

一、报错原文与一句话根因

以下文案按 Quartus 常见输出整理，工程名与路径均已占位：

1. 编译启动即断，.qsf 引用的源文件不存在：

Error (12007): Top-level design entity "demo_top" is undefined
Error: Quartus Prime Analysis & Synthesis was unsuccessful. 1 error, 0 warnings

2. 直接点名文件找不到：

Error: Can't find file "rtl/demo_top.v"
Error: File "D:/proj/demo/ip/pll_clk/pll_clk.qip" does not exist
Warning: File "../src/uart_rx.v" could not be opened for reading

3. Tcl / 命令行流程里报路径打不开：

Error: Can't read file "src/demo_top.v": no such file or directory
Error: Quartus project demo_top not found in directory "/home/user/work"

4. 打开工程时 Files 页整排红叉（不报错文字，但编译必断）：

Project Navigator → Files 页里文件名标红、带叉号图标，悬停提示 file not found。

一句话根因：Quartus 把每个源文件以路径字符串的形式记在 .qsf（Quartus Settings File）里，绝大多数是相对路径，基准是 .qsf 所在目录；一旦工作目录变了、文件被移动改名、IP 生成目录没随工程拷贝、或跨操作系统后分隔符与大小写语义不同，这条字符串就指向空处。 排查总原则只有一句：让 Quartus 把它实际要找的路径吐出来，拿去磁盘上对，而不是对着 .qsf 里的写法猜。

二、排查决策图

先用这张图定方向，再照第三节病因表对号入座。读图方式：从红色报错节点出发，蓝色是排查动作，命中根因走橙色修复分支，每修一步都回到「目标在磁盘上是否真实存在」重验，绿色为通过终点，紫色是收尾的防复发动作。

这张图覆盖六大根因中的前四类：相对路径基准漂移、跨系统分隔符与大小写、IP 生成目录未随拷贝、文件真的不在；剩下 SEARCH_PATH 缺失与特殊字符两类在第三节表里给验证命令。

三、病因处置表

报错现象	根因	快速验证	处置
工程拷来后 Files 页一排红叉	.qsf 相对路径基准是 .qsf 所在目录，目录层级变了	用文本编辑器打开 .qsf，看 set_global_assignment -name VERILOG_FILE 的路径与磁盘对比	恢复原目录层级，或改 .qsf 指向真实位置
Windows 正常，Linux 下一半文件找不到	反斜杠分隔符与大小写敏感差异	ls 对比报错路径，看大小写是否逐字符一致	.qsf 统一改正斜杠；文件名大小写改一致
文件被重命名/移动后编译报旧名	.qsf 记的是静态字符串，不跟随文件系统	在 .qsf 里 grep 报错文件名	Project → Add/Remove Files 重新指定，或手改 .qsf
模块文件在却报顶层未定义	SEARCH_PATH 没含源文件目录， Quartus 搜不到	Tcl 控制台 get_global_assignment -name SEARCH_PATH	set_global_assignment -name SEARCH_PATH "../lib"
只有 IP 相关文件（.qip/.sopcinfo）红叉	ip/ 或 qsys 生成目录没随工程拷贝	查工程下 ip 子目录是否为空或缺文件	重拷生成目录，或 Platform Designer 里重新 Generate
路径含空格/中文/& 等特殊字符	Tcl 解析或工具链外部命令被截断	报错路径在空格处断成两截	工程整体移到纯英文无空格路径下
编译中途报某个 include 文件找不到	头文件搜索路径未配，或宏路径基准不同	查报错文件是否在 SEARCH_PATH 覆盖内	加 SEARCH_PATH 或改 include 写法

四、三个最高频根因的修法

根因一：.qsf 相对路径基准漂移。 这是「工程从别的机器/同事拷来后一堆红叉」的标准答案。.qsf 里每条文件指派长这样：

set_global_assignment -name VERILOG_FILE rtl/demo_top.v
set_global_assignment -name VERILOG_FILE ../common/uart_rx.v

rtl/demo_top.v 相对的不是你当前打开 Quartus 的工作目录，而是 .qsf 文件自己所在的目录。同事工程里 ../common/uart_rx.v 引的是工程外共享目录，你只拷了工程文件夹，.. 上一层根本没有 common，自然全红。修法按优先级：恢复原目录层级 > 把共享目录一并拷来并调整相对深度 > 直接改 .qsf 指向新位置。改 .qsf 推荐在 GUI 里走 Project → Add/Remove Files in Project 删旧加新，比手编文本安全。

根因二：跨系统分隔符与大小写。 Windows 文件系统大小写不敏感，RTL/Demo_Top.v 和 rtl/demo_top.v 是同一个文件；Linux 大小写敏感，.qsf 里写 RTL/demo_top.v 而磁盘上是 rtl/Demo_Top.v 就直接 not found。同时 Windows 同事导出的 .qsf 可能带反斜杠 rtl\demo_top.v，Quartus 在 Linux 下不认。修法一步到位：把 .qsf 里所有路径统一成正斜杠，再逐条和 ls 的真实输出核对大小写。快速列出所有文件指派：

project_open demo_top
foreach a [get_all_assignments -name VERILOG_FILE] { puts $a }
foreach a [get_all_assignments -name SEARCH_PATH] { puts $a }

根因三：IP 生成目录与 SEARCH_PATH。 Quartus 的 IP（PLL、FIFO、Platform Designer 系统）会在工程下生成 ip/ 或同名生成目录，里面才是 .qip/.v 真身；只拷 .qpf/.qsf/rtl 三件套时这些引用全部悬空。要么把生成目录一起拷，要么打开 Platform Designer 重新 Generate HDL。另一类隐蔽的是 SEARCH_PATH：Quartus 找 include 文件和未显式登记的源文件时按 SEARCH_PATH 列表搜，库里文件挪了位置但搜索路径没更新，报错的措辞同样是找不到文件。补法：

set_global_assignment -name SEARCH_PATH "../common"
set_global_assignment -name SEARCH_PATH "./ip/pll_clk"

最后特殊字符单独提醒一句：工程路径含空格、中文、括号、&，GUI 里往往侥幸能过，一到命令行流程（quartus_sh --flow compile）或被 Tcl/外部脚本拼接时就截断出错。工程目录从第一天起就用纯英文、无空格、无特殊字符，是最便宜的保险。

五、修复后验证与防复发

修完不要只看「这次编译没红」。先对照 Files 页确认红叉清零，再用上面 get_all_assignments 把全部文件指派打印出来逐条对磁盘；然后 Analysis & Synthesis 全量重跑一遍，避免旧增量结果掩盖问题。

防复发三件事：其一，跨机器传递工程不要裸拷目录，用 Project → Archive Project 打成 .qar（Quartus Archive File），它能选「包含 IP 生成产物」，解开即完整可编译；其二，.qsf 入库版本管理，新同事 clone 后相对路径天然成立，但要约定工程外共享目录也用相对路径引用，禁止写绝对路径（D:/proj/... 一入库，换台机器必红）；其三，路径规范写进团队约定：纯英文、无空格、正斜杠、文件名与 .qsf 引用大小写逐字符一致。

另外养成一个肌肉记忆：每次工程搬家或接到别人发来的工程，第一件事不是点编译，而是先打开 Files 页扫一眼有没有红叉，再用 get_all_assignments 打印文件指派核对一遍磁盘。三十秒的预检能省掉对着一串 Error 12007 反推半小时的时间——顶层未定义、include 找不到、IP 悬空这三类报错的表面文案完全不同，根子却常常是同一条失效路径。模块级「文件在却找不到定义」的另一族问题，对照 Quartus 找不到模块速查；同样的相对路径基准问题在 Vivado 侧的 Tcl 版本，见 Vivado 路径/文件不存在速查。

一句话总结

Quartus 找不到文件/路径的本质是「.qsf 里记的路径字符串」与「文件实际位置」脱节：相对路径相对 .qsf 所在目录而非当前工作目录，跨 Windows 与 Linux 拷贝会撞上反斜杠与大小写敏感差异，文件移动改名后 .qsf 不自动跟随，SEARCH_PATH 缺项让 include 与库文件搜不到，IP 生成目录不随工程拷贝则 .qip 全部悬空；先用 Files 页红叉和 get_all_assignments 让缺失清单显形，再按恢复目录层级、统一正斜杠与大小写、补 SEARCH_PATH、重拷或重新生成 IP 产物逐条修复，工程传递统一走 Archive Project 的 .qar 闭环防复发。