极客工场

Appearance

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

Quartus 命令找不到速查：quartus_sh command not found 与「不是内部或外部命令」 ​

更新时间：2026-10-23。FAQ 速查页，面向在终端或脚本里直接调 Quartus 命令行工具（quartus_sh / quartus_map / quartus_fit 等）做编译自动化的同学。典型场景：GUI 明明装得好好的、双击能开工程，一到终端敲 quartus_sh --flow compile demo_top 就被 shell 顶回来一句 command not found。这类问题的根子几乎从不在 Quartus 本身，而在 shell 的 PATH 环境变量没指向 Quartus 的 bin 目录——装了软件不等于命令可寻址，中间隔着一层环境变量配置。命令能跑起来但报 license 错的，是另一条线，见 Quartus license 取不出来。

本文要回答的问题 ​

  • command not found 与「不是内部或外部命令」的报错原文各长什么样，说明什么？
  • 安装目录下那么多 bin / bin64 / nios2eds，到底哪个该进 PATH？
  • 装了多个 Quartus 版本时 PATH 指向旧版怎么查、怎么换？
  • Windows PATH 2048 字符截断、sudo 与用户 PATH 不一致、非交互 shell 不读 .bashrc 各是什么坑？
  • 怎么把配置写进 shell 启动文件，让新开终端永远可用？

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

以下文案按两个平台常见输出整理，路径均已占位。

1. Linux / macOS 终端敲命令直接被拒：

bash
$ quartus_sh --version
bash: quartus_sh: command not found

$ quartus_map demo_top
zsh: command not found: quartus_map

2. Windows cmd / PowerShell 里的对应形态：

text
C:\proj> quartus_sh --version
'quartus_sh' 不是内部或外部命令，也不是可运行的程序或批处理文件。

PS C:\proj> quartus_map demo_top
quartus_map: The term 'quartus_map' is not recognized as a name of a cmdlet...

3. 间接形态——makefile / 脚本里调用失败：

text
make: quartus_sh: No such file or directory
make: *** [compile] Error 127

一句话根因：shell 找命令只按 PATH 环境变量里列的目录逐个翻，Quartus 安装程序默认只装文件、不改你用户的 PATH（Windows 上装完勾选项例外），所以 quartus_sh 的可执行文件明明躺在安装目录 bin64 里，shell 却从来没去那个目录找过。 排查总原则：先用「找文件」而不是「找命令」的思路确认可执行文件在哪，再回头修 PATH。

二、排查决策图 ​

读图方式：从红色报错节点出发，蓝色是排查动作，先确认文件是否存在、再看 PATH 是否覆盖，命中根因走橙色修复分支，绿色为通过终点，紫色是防复发的固化动作。

fpga/ts-quartus-tool-not-in-path.md D2 示意图

这张图覆盖主流程：先定位文件、再核 PATH、区分多版本与特殊 shell 场景。六类根因的逐条验证命令在下一节表里。

三、病因处置表 ​

报错现象根因快速验证处置
装完 Quartus 后终端从未能用过命令安装程序没把 bin64 加进用户 PATHwhich quartus_sh 无输出；echo $PATH 里没有 Quartus 目录把 bin64 绝对路径追加进 .bashrc / .zshrc 或 Windows 环境变量
which 有输出但版本号不对装了多个版本，PATH 里旧版目录排在前面which -a quartus_sh 列出全部命中；quartus_sh --version 对版本号调整 PATH 顺序，新版目录放前；或写版本切换函数
GUI 能开，Nios II / 嵌入式工具链命令 not foundnios2eds 的环境脚本没 source，嵌入式 shell 未启动安装目录下找 nios2_command_shell.sh先启动 Nios II Command Shell，或在 .bashrc 里 source 环境脚本
Windows 上明明加过 PATH 却时好时坏系统 PATH 超 2048 字符被截断，Quartus 目录恰好在被截段echo %PATH% 看末尾是否完整；系统属性里检查 PATH 总长度精简 PATH 冗余项；把 Quartus 目录挪到前段；或用短路径重装
用户终端能用，sudo 下 not foundroot 的 PATH 与用户 PATH 是两套，sudo 默认重置环境sudo echo $PATH 对比 echo $PATH脚本内用绝对路径调用；或 sudo 时 sudo env "PATH=$PATH" 透传
交互终端能用，cron / CI / sh -c 里失败非交互非登录 shell 不读 .bashrc / .zprofilesh -c 'which quartus_sh' 复现失败配置写进 .profile 或 .zshenv；脚本开头显式 export PATH
命令找到了但启动即报版本错PATH 指到了和工程不匹配的版本目录quartus_sh --version 与工程要求的版本对号切换 PATH 指向匹配版本，参考版本排查另文

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

根因一：bin64 没进 PATH（占这类报错的八成）。 Quartus 的可执行文件按平台躺在固定位置：

  • Linux：/opt/intelFPGA_lite/23.1std/quartus/bin/quartus_sh（Lite 版路径含 intelFPGA_lite，Standard/Pro 对应 intelFPGA / intelFPGA_pro）
  • Windows：C:\intelFPGA_lite\23.1std\quartus\bin64\quartus_sh.exe（64 位系统在 bin64，老版本可能是 bin）

先确认文件真实存在，再把目录（不是文件本身）加进 PATH。Linux 下在 ~/.bashrc 或 ~/.zshrc 末尾追加：

bash
export PATH="/opt/intelFPGA_lite/23.1std/quartus/bin:$PATH"

保存后 source ~/.bashrc 或新开终端，跑 quartus_sh --version 应打印版本号。Windows 下走「系统属性 → 环境变量 → 用户变量 Path → 新建」，填入 C:\intelFPGA_lite\23.1std\quartus\bin64，改完必须重开 cmd 窗口才生效——已开的窗口读的是旧环境。

还有一个隐蔽变体：Nios II EDS（嵌入式开发套件）的 gcc、nios2-elf-gcc 这类命令不在 quartus/bin 里，而是由安装目录下的 nios2_command_shell.sh（Windows 对应 Nios II Command Shell 快捷方式）单独配环境。想在一个终端里同时用 Quartus 编译命令和嵌入式工具链，要么先启动 Nios II Command Shell 再补 export quartus 的 bin，要么在 .bashrc 里把两边目录都加进 PATH。只加一边、另一边报 not found，是新手最容易撞上的「配了但只配了一半」。

根因二：多版本共存时 PATH 指向旧版。 机器上同时装了 18.1 和 23.1 很常见（老工程要旧版编译）。which -a quartus_sh 会把 PATH 里所有命中按顺序列出来，第一条就是实际生效的。想临时切版本，不要反复改 .bashrc，写个函数更干净：

bash
quartus18() { export PATH="/opt/intelFPGA_lite/18.1/quartus/bin:$PATH"; }
quartus23() { export PATH="/opt/intelFPGA_lite/23.1std/quartus/bin:$PATH"; }

敲一下函数名就切，新开终端回到默认。工程对版本敏感、编译报「版本不兼容」类错误时，问题就从环境配置转到了工程层面，对照 Quartus 版本不兼容速查 处理。

根因三：非交互 shell 与 sudo 的环境落差。 这是「我终端里明明能用」一族的标准答案，背后是同一条规则：shell 启动文件按「登录/非登录、交互/非交互」分流加载——.bashrc 只在交互 shell 读，cron、CI runner、sh -c '...'、Makefile 子进程都属于非交互场景，自然读不到你写进 .bashrc 的 export。修法按场景：给自己用户长久生效就写 .profile / .zprofile（登录时读）；给脚本用，就在脚本开头显式写死：

bash
#!/bin/bash
export PATH="/opt/intelFPGA_lite/23.1std/quartus/bin:$PATH"
quartus_sh --flow compile demo_top

sudo 场景同理：sudo quartus_sh 用的是 root 的 PATH，稳妥做法是脚本里用绝对路径调用 /opt/intelFPGA_lite/23.1std/quartus/bin/quartus_sh，彻底绕开环境变量。Windows 侧 PATH 超 2048 字符被静默截断是同族坑：系统属性里编辑时会截，注册表直改也会截，表现就是「后加的条目不生效」，精简 PATH 或把 Quartus 目录前移即可。

五、修复后验证与防复发 ​

修完按三步验证：新开终端 which quartus_sh 确认指向预期版本的 bin 目录；quartus_sh --version 打印版本号与工程要求对号；拿一个真实工程跑一遍 quartus_sh --flow compile <工程名>，确认全流程不断。三步都过才算配置闭环，只过前两步可能在后续环节撞上 license 或版本问题——命令能启动之后报 license checkout 失败的，转 Quartus license 取不出来。

顺手把一组排查命令收进肌肉记忆，下次遇到任何「命令找不到」类问题（不限 Quartus）都是同三板斧：which -a <命令> 看 PATH 命中顺序、echo $PATH 看目录清单、find / -name "<可执行文件名>" 2>/dev/null（Windows 用 Everything 或资源管理器搜索）确认文件真实位置。先证明文件在，再证明 PATH 覆盖它，最后证明生效的是对的版本，三步必定位。

防复发三件事：其一，安装路径做成团队约定并写进新人 onboarding 文档——统一装到无空格纯英文路径（如 /opt/intelFPGA_lite/ 或 C:\intelFPGA_lite\），省去每个人 PATH 写法各不相同的沟通成本；其二，版本切换函数（上面 quartus18/quartus23 那种）放进共享的 dotfiles，而不是每个人手搓；其三，CI / cron / Makefile 里调 Quartus 一律用绝对路径或脚本开头显式 export，不依赖任何交互 shell 的启动文件——这条做到位，「我机器上能跑」这类扯皮直接绝迹。

一句话总结 ​

Quartus 命令找不到的本质是 shell 的 PATH 没覆盖安装目录的 bin/bin64：先用 find 或资源管理器确认 quartus_sh 真实位置，再用 which 与 echo PATH 核对是否覆盖及指向哪个版本；裸装未配置就追加 export 进 shell 启动文件，多版本冲突就调 PATH 顺序或写切换函数，sudo 与非交互 shell（cron/CI/Makefile）读不到 .bashrc 就在脚本内显式 export 或用绝对路径，Windows PATH 超 2048 字符被截断则精简或前移 Quartus 条目；修复后以 which、--version、真实工程全编译三步验证，安装路径约定与版本切换函数写进团队文档防复发。