Quartus 依赖缺失报错速查：器件支持没装、仿真库没编译与外部库路径丢失怎么办
更新时间：2026-10-23。FAQ 速查页，属于 FPGA 工具报错排错系列。Quartus 依赖缺失报错最坑的地方是：报错文案里清一色都是「not found / can't find / not installed」，但缺的东西分属五个完全不同的层次——Quartus 安装时没勾选的器件族支持包、需要单独安装的 IP 核、没编译的 ModelSim 仿真库、没随工程走的外部库搜索路径、以及 git 仓库里漏提交的 IP 生成物。五层的补齐动作互不通用，装错方向纯属浪费时间。本篇以真实报错文案为锚做一次分流。路径写法本身有误的姊妹篇见 Quartus 找不到文件/路径速查，Xilinx 阵营的对照篇见 Vivado 依赖缺失速查。
本文要回答的问题
- 编译报
device family "Cyclone V" is not installed，Quartus 明明装好了为什么还缺？ - 工程里的 PLL/RAM 等 IP 核打不开，提示 IP 找不到或要求重新安装，缺的是什么？
- ModelSim 启动仿真报库找不到（如
altera_mf未映射），仿真库要去哪编译？ - 工程引用了团队公共库，拷到自己机器就报模块找不到，路径去哪配？
- git clone 下来的工程一编译就缺 IP 文件，仓库里到底该提交哪些生成物？
一、报错原文与典型现象
以下路径与工程名均为占位（D:/proj/demo、demo_top），报错编号以 Quartus 真实风格给出。
1. 器件族支持包没装——Quartus 能启动，工程打不开或编译第一步就挂。
Error (11239): The device family "Cyclone V" is not installed.
Please install the device family support for "Cyclone V"
using the Quartus Prime installer or the Device Installer.Quartus Prime 的安装器把软件本体和各器件族支持包（Cyclone、Arria、Stratix、MAX 等）拆成独立组件，安装时只勾了手头在用的那族，换个族的工程拷过来就报这个错。Lite 版与 Standard/Pro 版支持的器件族清单也不同，装错版本同样命中。
2. IP 核没装或 license 缺失——器件族在，但 IP 打不开。
Error: IP Generator Tool: Can't find IP "altera_pll" in the installed IP libraries.
Error: The IP core "xxx" requires a separate installation or license.Quartus 自带的基础 IP（PLL、RAM、FIFO 等）随器件支持包安装，但部分高级 IP（如某些协议栈、视频处理 IP）需要单独下载安装包；还有一部分需要付费 license，没授权时 IP catalog 里能看到、生成时却被拦。授权类报错的细节分流到 Quartus license 取不出来速查，本篇只管「东西没装上」的情形。
3. ModelSim 仿真库未编译——综合能过，仿真起不来。
# ModelSim/Questa 启动仿真时：
Error: (vsim-3033) ... Instantiation of 'altera_mf.xxx' failed.
The design unit was not found.
# 或 Nativelink 直接提示：
Error: Can't run simulation: simulation libraries for
"Cyclone V" have not been compiled.Quartus 出厂不带编好的仿真库，altera_mf、lpm、cyclonev 这些库要先在本机用对应版本的仿真工具编译一遍，这是换机器、换 Quartus 版本后仿真必挂的经典原因。
4. 外部库搜索路径没配——模块在仓库里有，编译器找不到。
Error (10170): Verilog HDL syntax error at xxx.v(n) near text...
Error (12007): Top-level design entity "demo_top" is undefined
# 实际是引用的公共库目录没进 SEARCH_PATH，模块声明全丢工程 .qsf 里的 set_global_assignment -name SEARCH_PATH 如果写的是同事机器上的绝对路径，工程一换机器整条路径失效，所有来自公共库的模块同时「失踪」，表象和模块没写一模一样（区分方法见 Quartus 找不到模块速查）。
5. git 仓库没提交 IP 生成物——clone 下来一片红。
Error (12006): Node instance "pll_0" instantiates undefined entity "pll".
Error: Can't find file .../ip/pll/pll_0002.v仓库里只提交了 .qip 却漏了 .qip 引用的生成目录（或相反），新机器上 Quartus 按 .qip 索引去找 HDL 文件时扑空。
二、现象 → 病因 → 处置速查表
| 报错现象 | 缺的是哪一层 | 一判据 | 处置方向 |
|---|---|---|---|
device family ... is not installed | 器件族支持包 | 打开工程或 Analysis 第一步即报 | 用 Device Installer 补装对应器件族，或核对 Lite/Standard 版本 |
| 基础 IP（PLL/RAM）catalog 里没有 | 器件支持包不完整 | 新建 IP 时列表缺基础项 | 补装器件包后重启 Quartus |
| 高级 IP 提示需要单独安装 | 独立 IP 安装包 | 该 IP 不在自带清单内 | 从厂商下载对应 IP 安装包，与 Quartus 版本对齐 |
| IP 能生成但仿真/综合报 license | 授权缺失 | 报 license checkout 类信息 | 走授权通道，见 Quartus license 取不出来速查 |
仿真报 altera_mf/lpm 库找不到 | 仿真库未编译 | 综合能过、vsim 起不来 | 用 EDA Simulation Library Compiler 按版本重编 |
| 换 Quartus 版本后仿真全挂 | 仿真库版本错位 | 库目录是旧版本编出的 | 清掉旧编译产物，用新版本工具重编 |
| 公共库模块集体 undefined | SEARCH_PATH 失效 | 路径指向别人的盘符/家目录 | .qsf 改相对路径并重配 SEARCH_PATH |
| clone 后报 IP HDL 文件找不到 | 生成物提交不全 | 仓库里只有 .qip 没有生成目录 | 补齐提交或在本地 Platform Designer 里重新 Generate |
| 工程在别人机器一切正常 | 环境层缺失 | 逐台机器对比安装组件清单 | 对照「防复发」一节做环境清单 |
三、排查决策树
分诊只看两件事：报错在哪个阶段抛出（开工程 / 综合 / 仿真），缺的东西属于五层中的哪一层。下图颜色含义：红=报错入口与命中的根因层，蓝=分诊动作，橙=对应修复动作，绿=流程恢复，紫=防复发沉淀。
direction: down
entry: "Quartus 报依赖缺失\nnot found / not installed / undefined"
classify: "看报错阶段与缺失对象\n开工程 / 综合 / 仿真"
devfam: "器件族支持包未装\ndevice family not installed"
ipmiss: "IP 核未装或未生成\n基础 IP 缺 / 高级 IP 单独装"
simlib: "ModelSim 仿真库未编译\naltera_mf 等库未映射"
libpath: "外部库路径失效\nSEARCH_PATH 指到别人机器"
pass: "重开工程重跑全流程\n综合与仿真通过"
prevent: "沉淀环境清单与提交规范\n写进团队 README"
entry -> classify
classify -> devfam: "开工程/分析第一步报"
classify -> ipmiss: "IP 打不开或 HDL 文件缺"
classify -> simlib: "综合能过、vsim 起不来"
classify -> libpath: "公共库模块集体失踪"
devfam -> pass: "Device Installer 补装器件包"
ipmiss -> pass: "补装 IP 或重新 Generate"
simlib -> pass: "重编仿真库并核对映射"
libpath -> pass: "SEARCH_PATH 改相对路径"
pass -> prevent
devfam -> pass.style.stroke: "#E08A1E"
ipmiss -> pass.style.stroke: "#E08A1E"
simlib -> pass.style.stroke: "#E08A1E"
libpath -> pass.style.stroke: "#E08A1E"
entry.style: { fill: "#FDECEC"; stroke: "#D9534F" }
classify.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
devfam.style: { fill: "#FDECEC"; stroke: "#D9534F" }
ipmiss.style: { fill: "#FDECEC"; stroke: "#D9534F" }
simlib.style: { fill: "#FDECEC"; stroke: "#D9534F" }
libpath.style: { fill: "#FDECEC"; stroke: "#D9534F" }
pass.style: { fill: "#E9F8F0"; stroke: "#2E9E6B" }
prevent.style: { fill: "#F1ECFD"; stroke: "#7A5BD4" }读这张图抓住一个分叉：五层根因互不相通——器件族没装时去重编仿真库毫无用处，SEARCH_PATH 失效时重装 Quartus 也救不回来。任何一个橙色修复动作做完，都要回到绿色节点：重开工程、完整跑一遍分析与综合加仿真确认闭环，然后落到紫色节点把这次的坑写进环境清单，不要修完就撒手。
四、逐条排查展开
器件族支持包：用 Device Installer 补装，不重装整个 Quartus。 Quartus 的器件支持是按族拆分的独立安装单元，主菜单 Tools → Install Devices 调出 Device Installer，勾选缺的器件族（注意 Quartus 版本必须与工程创建时大版本对齐，18.1 的器件包塞不进 20.1），装完重启软件即可。装之前先确认版本档位：Lite 版只覆盖 Cyclone/MAX 等入门族，Arria/Stratix 必须 Standard/Pro 版——报 not installed 而器件族又是高端族时，先怀疑装的是 Lite。
IP 核：先分清「没装」还是「没生成」。 基础 IP 缺失基本是器件包不完整的连带症状，补装后 IP catalog 会恢复。高级 IP 看厂商发布页下载与 Quartus 版本对应的独立安装包。git 工程里的 IP 报 HDL 文件找不到时，先别急着补装：打开 Platform Designer（Qsys）加载 .qsys，点 Generate HDL 重新生成一遍——很多团队只提交 .qip 与 .qsys 源，生成物由各人本地产出。要提交生成物就一次提全：.qip 里索引的每个 .v/.vhd、.sdc、仿真模型一个都不能漏，半截提交比不提交更害人。
仿真库：EDA Simulation Library Compiler 一次编齐。 Tools 菜单里启动该工具，选对仿真器（ModelSim Intel FPGA Edition 或外置 Questa）、语言（Verilog/VHDL）、器件族与输出目录，跑完会在输出目录生成编译好的库与 modelsim.ini 映射。三个坑最常见：换了 Quartus 版本后旧库没重编（库与工具版本强绑定）；ModelSim 启动目录里的 modelsim.ini 没指向新库路径（vmap 核对映射）；混用了多个 Quartus 版本编出的库。编完用一次最小测试激励起仿真验证，再开正式工程。
外部库路径：SEARCH_PATH 一律相对工程根。 .qsf 里推荐写法：
set_global_assignment -name SEARCH_PATH ../common_lib
set_global_assignment -name SEARCH_PATH ./ip绝对路径（D:/zhangsan/libs 这类）是换机即死的头号来源；路径规则的更多细节见 Quartus 找不到文件/路径速查。改完 .qsf 后重新 Analysis，如果模块仍 undefined，按 Quartus 找不到模块速查 的判据确认是路径没生效还是模块本身缺失。第三方库还要确认文件的 VLOG_FILE/VHDL_FILE 指派是否齐全——SEARCH_PATH 只解决 include 与模块解析，不参与文件列表。
五、预防与纪律
- 新机器先过安装清单：把「Quartus 版本 + 器件族包 + 独立 IP 包 + 仿真库编译」写成团队初始化文档，装完编译一次 demo 工程再交机器。
- IP 生成物提交策略定死一种：要么全提交生成目录并在 README 声明，要么只提交源文件并要求 clone 后先 Generate——两种混着来必然出半截仓库。
- SEARCH_PATH 禁绝对路径：code review 时 grep 一遍
.qsf，出现盘符或他人家目录直接打回。 - 仿真库版本随 Quartus 版本走：升级 Quartus 的同一动作里重编仿真库，清掉旧编译产物，新旧库不混放。
- 分清五个层次再动手：器件包、IP 安装、仿真库、库路径、仓库完整性各自独立，重装软件永远是最后选项而非第一反应。
这一篇在知识体系里的位置
本篇是 FPGA 工具报错排错簇中 Quartus 侧「依赖缺失」的分流页：文件路径写法本身有误看 Quartus 找不到文件/路径速查；路径对了模块仍解析不到看 Quartus 找不到模块速查；依赖被授权拦住看 Quartus license 取不出来速查；Xilinx 阵营的同主题对照看 Vivado 依赖缺失速查。
一句话总结
Quartus 依赖缺失报错先按报错阶段把缺失物分五层：开工程报 device family not installed 是器件族支持包没装，用 Device Installer 补装、注意 Lite/Standard 档位；IP 打不开要分清没装（器件包不全或高级 IP 需单独安装包）与没生成（Platform Designer 重新 Generate）；仿真报 altera_mf 等库找不到是仿真库没编，用 EDA Simulation Library Compiler 按当前版本重编并核对 modelsim.ini 映射；公共库模块集体失踪是 SEARCH_PATH 写了绝对路径，改相对工程根；clone 后 IP HDL 缺文件是仓库生成物提交不全，补齐或本地重新生成；根治靠安装清单、提交策略与相对路径三件套。