1. 先说清楚Vitis 到底是个什么东西为什么环境配置这么折腾Vitis 是 AMD原赛灵思 Xilinx推出的统一软件平台核心目标是把 FPGA、SoC、异构加速卡、Versal 自适应计算平台这些硬件全部纳入同一套开发流程。在我早些年搞 Zynq 嵌入式开发的时候还要在 Vivado 和旧版 SDK 两个工具之间来回切换硬件工程一个界面软件工程又一个界面链路稍微复杂一点就手忙脚乱。Vitis 把平台工程、应用工程、硬件加速核、软硬协同调试、AI 引擎这些全部整合到了一个 IDE 生态里思路确实比老一套清晰太多。但话说回来工具再强第一步“安装和环境配置”就能劝退一大批人。这东西不是装个普通软件双击下一步那么简单组件怎么选、器件支持包怎么勾、环境变量怎么设、license 怎么点、和 Vivado 版本怎么匹配每一步都有讲究。我这些年从 2019.2 一路装到 2023.2、2024.1在 Windows 和 Linux 上都踩过不少坑有的坑真的很低级——比如磁盘少了 10GB 安装器直接中途消失又比如 source 环境变量少敲一次打开终端就找不到 vitis 命令。这篇我就把整套流程完整梳理一遍从下载之前要想清楚什么到安装时怎么勾选组件再到环境变量、license、跑通第一个 hello world以及那些文档里根本没写、只有实际操作才会撞上的问题一次说清楚。适合刚接触 Vitis、准备在个人电脑上搭环境的人参考也适合本来就会用但被版本升级折腾到怀疑人生的人用来避坑。2. 版本和安装包选型这一步想岔了后面全白干2.1 版本选择不是“新版本就一定好用”我在很多群里看到新手问的第一句话就是“最新版在哪下”这个心态我非常理解但 Vitis 这个工具和普通软件不太一样选版本要考虑三点硬件平台、操作系统、以及你手上有没有对应的板卡支持包。如果你用的是 Zynq UltraScale MPSoC 开发板厂商一般会注明官方支持哪个版本的 Vitis。你非要在这块板上强上最新版大概率会遇到 BSP 不匹配的问题最后还得手动打补丁。反过来如果你准备做 Versal 平台开发老版本 Vitis 根本不认识 Versal 器件选了也是白选。所以选版本的第一原则是“以板卡和器件为准而不是追求新”。另外还要看操作系统兼容性。每一个 Vitis 版本发布时都会有一份 release notes里面明确写了支持哪些 Ubuntu 版本、最低内存、磁盘要求。比如 Ubuntu 22.04 装某些旧版本 Vitis就经常遇到缺 libtinfo5 这类老库的问题你光装新版本工具链根本不管用。所以我每次下载前都会先翻一遍 release notes确认我这台机器的系统在支持列表里省得装到一半才发现根本跑不起来。2.2 硬件门槛Vitis 不是装完就能跑起来的先说结论一台 16GB 内存的电脑能把 Vitis 装上但用起来会很难受。IDE 本身是基于 Eclipse 的启动就要吃不少内存再打开几个工程、跑一下综合编译内存占用轻轻松松冲到 10GB 以上。我个人的建议是 32GB 内存起步如果条件允许直接上 64GB体验完全不一样。磁盘空间才是最容易出问题的点。Vitis 完整安装包含 Vivado 工具链、Vitis IDE、Vitis HLS、嵌入式交叉编译工具链、QEMU 模拟器、以及各器件系列的支持包。如果把所有器件系列都勾上两三百 GB 都很正常。哪怕只装自己用得到的器件官方推荐的预留空间也在 200GB 左右实际装下来我见过最少 130GB 的通常不会低于这个数。所以装之前先看看磁盘剩余空间别等到安装器走到一半直接中断那个教训很痛。操作系统方面Windows 10 和 Linux 我都试过。个人折腾建议直接用 LinuxUbuntu 20.04 或 22.04不是说 Windows 不行而是很多后期要用的工具链、脚本、固定流程都是先为 Linux 设计的你在 Windows 上遇到的问题往往要额外去论坛翻解决方案。嵌入式开发如果后面要接 Petalinux 这类工具那更是绕不开 Linux。如果你只是想做 Vivado 硬件开发Windows 倒是够用。2.3 安装包下载一份心思少等几个小时的坑现在 Vitis 的下载方式有两种一种是直接在 AMD 官网用统一安装器Unified Installer在线安装另一种是先把完整的 .tar/.exe 安装镜像下载到本地再离线安装。在线安装适合网络非常好、且你不介意安装过程“下载一下、装一下、又下载一下”这种反复操作的情况。但问题在于 Vitis 的安装镜像动辄几十 GB在线安装一旦中途断网有些安装器能从断点继续有些不能如果崩溃了你可能得从头来过。所以我的建议是宁可多花点时间提前把离线包拖下来也别赌安装过程的网络稳定性。下载之前需要先注册 AMD 账号这个不难但要注意下载页面上各个组件包的区别。到了近几个版本Vitis 已经不像以前那样一股脑地和 Vivado 捆在一起装了比如 2024.1 之后的安装方式就有明显调整Vitis 本身也拆成了核心工具、AI 引擎工具、嵌入式工具等多个可选项。别看到哪个都点下载先看清楚说明弄清楚自己到底需要哪一块不然一个下午都耗在下载上也只是把一堆用不到的包拖了回来。3. 安装流程实录从双击到安装完成中间全是细节3.1 图形界面安装新手最不容易出错的路径虽然我是一个习惯用命令行的人但 Vitis 的安装我还真建议走图形界面尤其是第一次装的人。因为 Vitis 安装器的图形交互界面已经封装好了版本检测、依赖检查、组件管理你只需要一路确认就行。批处理静默安装虽然省事但如果参数不对出错之后排查反而更麻烦。以 Linux 为例解压完安装包之后在安装包目录下会看到一个可执行文件名字通常是xsetup给它加执行权限后启动。Windows 上则是双击xsetup.exe。首次启动会进入欢迎界面要求登录 AMD 账号这一步用来校验下载权限和发放免费 license 相关的东西。有朋友担心没有账号就不能装其实注册是免费的放心弄。安装界面里最关键的一步是选择版本和产品组合。老版本通常是 Vivado 和 Vitis 一起选新版本可能分得更细。无论界面怎么变记住一个原则只装自己需要的组件。我见过有人图省事把所有器件系列全部勾上结果磁盘直接被吃掉了三百多 GB安装时长也翻了倍。如果你用的是 Zynq UltraScale MPSoC那就只需要勾 UltraScale 系列的器件支持如果做 Kria 或者 Versal再对应勾选。后面要补装也随时可以运行安装器增加组件没必要一次全装。3.2 组件勾选会勾组件等于给自己省了几小时组件这块我展开多说几句因为太多人在这里栽跟头。Vitis 安装界面里一般会出现Vivado硬件设计工具、Vitis IDE嵌入式/应用软件开发、Vitis HLS高层次综合、嵌入式交叉编译工具链、QEMU、U-Boot 和 Linux 相关组件等。如果你是做 SoC 嵌入式开发Vivado 和 Vitis IDE 都得装因为要先用 Vivado 生成硬件平台XSA 文件再把平台导入 Vitis 去跑软件。如果你只是想试试 Vitis HLS 做算法加速那 Vitis IDE 可以适当精简但 Vivado 还是跑不掉因为最终要生成 bitstream 下去调试。有一个很容易被忽略的地方是“安装路径”。Linux 下我强烈建议装在/tools/Xilinx这类简单路径下Windows 下也尽量避开中文路径和带空格的目录。倒不是说工具绝对跑不起来而是后续用脚本、Makefile、交叉编译链的时候路径里一旦出现空格或者中文各种诡异问题就出来了你说不清是环境的问题还是代码的问题。3.3 Windows 安装过程里的额外注意点Windows 上安装 Vitis 比 Linux 多两个需要手动留意的点杀毒软件和 JTAG 驱动。杀毒软件有时候会把安装器生成的临时文件当作病毒给隔离掉导致安装到百分之六七十突然失败也没有任何明确提示。我自己的处理办法是安装期间暂时退出安全软件装完再恢复。如果已经安装失败过一次建议把安装目录和缓存目录添加白名单再重试。JTAG 相关驱动则是 Windows 上连开发板调试时必需的。安装界面里一般会有一个 Cable Drivers 的选项默认可能没勾如果你后面要用调试器下载程序这个不装会非常尴尬。装完之后插入 JTAG 设备设备管理器里应该能看到对应的调试器设备看不到就说明驱动没装对。3.4 Linux 安装后的依赖库补丁Linux 环境安装完 Vitis 后直接启动有时候会报错最常见的是libtinfo.so.5 not found这类动态库缺失。这不是 Vitis 本身没装好而是系统里缺少老版本库。新的 Ubuntu 版本默认只带新库不带这些兼容版本解决办法是把对应的老库补上。以 Ubuntu 22.04 为例如果遇到 libtinfo5 缺失可以通过系统包管理添加对应来源后安装。这个库是为了兼容旧版工具链像 Vitis 这种大工具包含的组件跨度大很多底层交叉编译工具还在依赖旧库不能怪工具不上进只是维护历史包袱太重了。注意在装 Linux 依赖库之前先确认你用的发行版和版本号。不同发行版的包管理不同同是 Ubuntu22.04 和 20.04 的处理方式也不完全一样盲复制网上的命令有时候反而会把系统环境搞乱。4. 环境配置是最关键的一步千万不能跳过4.1 环境变量每次开终端都要做的动作安装完成不代表你可以直接用这个坑几乎每个新手都会踩。装好 Vitis 之后你需要先配置环境变量才能让系统找到 vitis、vivado 这些命令。Linux 下 Vitis 安装目录里提供了一个环境变量脚本路径类似/tools/Xilinx/Vitis/2023.2/settings64.sh每次打开新的终端都要执行一次source /tools/Xilinx/Vitis/2023.2/settings64.sh这个脚本会设置XILINX_VITIS、PATH、LD_LIBRARY_PATH等一堆环境变量。没有这些变量你打开终端输入 vitis系统只会告诉你命令找不到。每次都手动 source 太容易忘了尤其你开着多个终端的时候。我个人的做法是把它写进 shell 配置文件里这样每次打开终端自动生效。以 bash 为例echo source /tools/Xilinx/Vitis/2023.2/settings64.sh ~/.bashrc source ~/.bashrc如果你用的是 zsh对应改~/.zshrc。写进去之后开新终端验证一下直接输入which vitis能打印出路径就算成功了。Windows 上稍微不一样安装器一般会自动加一些路径但为了保险你还是可以手动把Vitis的bin目录添加到系统 PATH 里否则在命令行里同样找不到 vitis 命令。4.2 License 配置账号有工具未必认Vitis 需要 license 验证才能完整使用。对于免费用户可以使用 AMD 官网申请到的评估 license 或 Vivado WebPACK 对应的免费 license。需要注意的是WebPACK 对器件规模有限制中小规模器件没问题部分大规模芯片和 Versal 系列就需要 Standard 或 Enterprise 版本的 license。申请 license 的关键点是填硬件信息。官网会让你提供电脑的 MAC 地址或者主机 ID然后给你生成一个 .lic 文件。这里我吃过亏有些电脑有多块网卡安装时显示的网卡信息和系统激活时实际用的不是同一块申请下来的 license 校验不通过。解决办法是先确定你安装工具时用来申请的那块网卡的 MAC 地址保证填写信息与系统一致。拿到 .lic 文件后Linux 下可以设置环境变量XILINXD_LICENSE_FILE指向该文件export XILINXD_LICENSE_FILE/home/yourname/xilinx.licWindows 则可以在 Vitis IDE 菜单栏的 Tools 里打开 License 设置界面直接添加许可证文件比配环境变量直观很多。还有一个坑是如果 license 文件的路径里带着中文或者空格工具解析时也可能出问题。License 文件这种东西路径就老老实实保持简单吧别用桌面路径。对了桌面是/home/xxx/Desktop如果你桌面在网盘同步目录里也容易出幺蛾子建议把 .lic 放到专门的工具配置目录。4.3 Vivado 和 Vitis 的版本匹配这个必须单独拉出来说因为它的坑实在太多了。Vitis 和 Vivado 是两个工具但新版 Vitis 里的很多功能依赖 Vivado 生成的平台文件。如果你用 Vivado 2022.2 导出的 XSA 文件放到 Vitis 2023.1 里去创建平台大概率会报版本不匹配的错误。这里没有太多技巧就是必须保证 Vivado 和 Vitis 的大版本一致比如都是 2023.2不能一个 2022.2 一个 2023.1。我见过有人把 Vivado 2023.1 和 Vitis 2023.1 装在了不同目录但环境变量脚本只 source 了 Vitis 的结果调用 Vivado 相关的功能时版本对不上。正确的顺序是先 source Vivado 的 settings64.sh再 source Vitis 的 settings64.sh保证工具链路径优先指向匹配版本。具体哪个先后取决于安装器生成的配置我建议你分别在 Vitis IDE 里检查一下报告出来的是哪个 Vivado 版本保险。4.4 XRT 运行时跑加速应用时需要额外设置如果你做的是 Vitis 硬件加速比如把 OpenCL 内核跑到 FPGA 加速卡上那还需要注意 XRTXilinx Runtime的环境设置。XRT 是连接应用层和硬件层的运行时环境装完 Vitis 后通常会一起装上但需要单独 source 它的脚本目录一般在/opt/xilinx/xrt下面source /opt/xilinx/xrt/setup.shsource 之后可以用xbutil examine这样的命令检查是否能识别到加速卡。这一步在纯嵌入式开发直接在 SoC 上跑裸机或 Linux时未必用得上但如果你后面要碰 OpenCL 加速或者 Versal AI Core 相关开发就跑不掉。我建议干脆一起配置好省得到时候再补。环境配置这部分说完我想强调一个点环境变量真的不冲突。很多人担心把 Vitis、Vivado、XRT 的环境变量都 source 会打架其实只要版本一致它们的脚本是能互相兼容的。真正打架的情况基本都发生在新旧版本混装这时候最干净的做法是彻底卸载干净重装别在路径上改来改去浪费的时间更多。5. 跑通你的第一个 Vitis 工程验证环境真的没问题5.1 先做工具链检查不急着开 IDE配置完环境之后我的习惯是先不急着打开 IDE而是在终端里快速验证一遍工具链是否可用。Linux 下依次执行which vitis which vivado vitis -version vivado -version前两个能返回路径后两个能正常打印版本信息说明核心工具已经就绪。如果which vitis没有输出回头检查 4.1 里的环境变量是不是真的 source 进去了。接着检查交叉编译工具链有没有装好。以 Zynq UltraScale MPSoC 的 ARM Cortex-A53 交叉编译链为例你可以找一下aarch64-linux-gnu-gcc是否在 PATH 里。Vitis 内置的交叉编译工具链在安装目录的gnu/aarch64/nt/aarch64-linux-gnu/bin或者类似路径下。如果找不到回到安装器里把嵌入式工具链组件补装上。Windows 下检查方式类似在 PowerShell 或命令提示符里输入vitis -version。需要注意 Windows 下环境变量修改后必须重新打开一个终端窗口才会生效旧窗口里的环境变量不会自动更新这个很容易被忽略。5.2 创建 hello world 平台工程基本工具链没问题后就可以跑一个最小工程来验证整套环境。以嵌入式开发方向为例最顺手的做法是利用 Vitis 自带的预建平台跑 hello world。打开 Vitis IDE命令就是vitis在欢迎界面选择工作空间目录。工作空间你可以理解成 IDE 放工程文件的地方路径里同样别带中文。接着创建 Application Project到了选择 Platform 那一步选择 Vitis 自带的一个基础平台模板比如基于 Zynq 或 MPSoC 的“bare metal”版本。随后选择模板里的 Hello WorldVitis 会自动帮你生成一个最简单的 C 程序主要是打印一行字符。最后选择编译编译通过后会生成 ELF 文件。跑这一点环境配置基本就是通的了。如果你有开发板可以连接 JTAG 下载到板上运行没有的话可以在 Vitis 里用 QEMU 仿真这个功能对验证环境非常有用。QEMU 不需要额外装任何东西Vitis 安装目录里已经带了。用它跑 hello world 不需要板卡能直接看到终端输出等于你已经完整走了一遍“编译 运行”的流程。5.3 命令行方式不习惯 IDE 也能快速验证有些人不喜欢开图形界面或者在做自动化编译的时候会直接用命令行创建和编译 Vitis 工程。这里给一个最简验证思路先用 source 配置好环境然后创建一个 workspace 目录在目录里用 Vitis 的命令行工具创建应用工程再用 make 编译。由于不同版本命令行工具有所差异我先不写死具体参数但思路都是通过vitis命令配合 workspace、platform、app 这些子命令完成创建。你自己敲vitis -help就能看到当前版本支持的命令。不过如果你是第一次接触 Vitis我还是建议先老老实实把 IDE 跑通一遍图形界面能让你直观看到哪里报错对排查环境问题有巨大帮助。命令行等你熟悉了工程结构后再上不迟。6. 常见问题与排查实录这些坑我替你踩过了6.1 终端找不到 vitis 命令这个问题十次有八次是环境变量没生效。先执行source脚本再在当前终端里试。如果当前终端没问题新开一个终端又不行说明没写入 shell 配置文件。写进去之后还是不行看一下安装路径是否存在有时候安装器让你自定义路径你选完自己却忘了装在哪了。Windows 下还有一种情况是 PATH 变量加错了目录。注意不是把 Vitis 的根目录加进去而是要加到底下有vitis.exe的 bin 目录。6.2 License 报错不是你的 license 有问题是指向有问题常见报错信息类似Invalid license key或者Unable to checkout Vitis。排查思路分三步第一步确认 .lic 文件里的 MAC 地址和系统网卡硬件地址一致第二步确认环境变量XILINXD_LICENSE_FILE已经正确设置而且路径没有写错第三步确认 license 在有效期内评估 license 通常有三个月或一年期限过期了就得重新申请。有一个比较隐蔽的坑是系统里同时安装了其他 EDA 工具的 license 管理变量比如有的开发环境LM_LICENSE_FILE被第三方软件占用导致 Xilinx 工具找不到自己的 license。建议把XILINXD_LICENSE_FILE单独设置不要混用LM_LICENSE_FILE。6.3 IDE 启动异常闪退、白屏、报 JVM 错误Vitis IDE 基于 Eclipse底层依赖 Java对系统环境和显卡驱动比较敏感。Linux 上最常见的问题是缺少图形库或者显卡驱动不兼容表现为启动后白屏或者干脆起不来。排查时先看终端输出有没有报明显的动态库错误有的话按提示补装对应库。另一个常见问题是内存太小。Vitis IDE 启动时默认会分配内存如果你的机器内存只有 8GB同时开着浏览器和文档很可能直接 OOM 闪退。可以关闭其他应用后再试试如果还是不行考虑调整 IDE 的启动参数减少初始堆内存。Windows 上如果遇到启动后界面消失优先检查杀毒软件有没有把 Vitis 的可执行文件隔离。我遇到过装完第二次启动被杀毒软件把关键 DLL 删了的情况当时排查了很久最后才发现是安全软件干的。6.4 Vivado 和 Vitis 版本不匹配的工程打开失败当你用 Vivado 导出 XSA 文件然后在 Vitis 里创建平台工程时如果报错说是平台文件版本不匹配先别怀疑文件坏了先看两个工具的大版本号。请确保两个工具版本完全一致。不一致的话要么用匹配的 Vivado 重新导出 XSA要么把 Vitis 升级到对应版本。这个问题在团队协作时特别常见。同事用 Vivado 2023.1 导出的平台文件发给你你电脑上装的是 Vitis 2023.2打不开很正常。标准做法是团队内部统一版本不能各装各的。6.5 安装过程突然失败或进度条卡住大文件安装失败原因我遇到过的集中在三类磁盘空间不足、网络中断、安全软件干扰。磁盘空间不足有时候很隐蔽不是根目录满了而是你选的安装目录所在分区满了。安装器在检查时未必能立即发现要等真正写文件时才会失败。如果你是 SSD 加机械盘的组合尤其要留意安装目录所在分区的剩余空间。网络中断多发生在在线安装模式解决办法是尽量用离线完整安装包。如果必须在线安装可以尝试更换更稳定的网络环境别用容易断线的网络。安全软件干扰则多发生在 Windows 平台安装前暂时退出安全软件安装完成后再恢复防护。6.6 小技巧验证环境是否正常的“三板斧”最后分享一个我每次装完新环境必做的小流程算是快速健康检查第一板斧确认环境变量能加载。新开终端执行source后用which vitis看路径。第二板斧跑一次版本查询。vitis -version和vivado -version能正常输出版本号说明动态库没大问题。第三板斧建一个最小 hello world 工程并完成编译。这一步能排查掉很多只在编译阶段暴露的问题比如交叉工具链配置、license 校验、路径环境等。这三个环节全部通过这个环境的可靠性就有保障了。后续再遇到问题基本可以确定是工程本身的问题而不是环境的问题排查范围一下就缩小了很多。我在实际使用中还有一个习惯就是每次重装系统或者换新电脑后都会把安装过程的每一步简单记下来尤其是环境变量脚本路径和 license 文件放在哪里。时间久了真的会忘记等半年后再重装一次又要花半天时间去回忆当初是怎么配的。其实 Vitis 本身不复杂复杂的是它依赖的那一整套环境细节把这些细节理清楚后面的开发才会顺。