PetaLinux 和 SDK 的安装，说难不难，说简单也真不简单。我前前后后在不同电脑上装过七八次，踩过的坑比教程里的步骤还多。这篇就只聊安装，从版本选型、环境准备、实际操作到报错排查，把最容易翻车的几个地方一次说清楚。内容主要面向三种人：第一次接触 FPGA SoC 平台 Linux 开发的初学者、要帮团队搭建统一开发环境的技术负责人、以及被某个诡异报错卡了两天准备砸电脑的兄弟。

1. 安装前的思路与版本选型

1.1 为什么一定要用 PetaLinux，而不是手动做交叉编译

聊安装之前，有些事情得先想明白。在带 CPU 的 FPGA 平台上做嵌入式 Linux 开发，通常有两种路线。一种是自己用 Linaro 或者其他工具链，手工搭建交叉编译环境，再自己写设备树、编 bootloader、定制根文件系统。这条路线的最大问题是每换一个板卡，设备树、启动引导、文件系统配置都要重新做一套，而且很多底层的细节在没有厂商工具辅助的情况下，光是定位一个 kernel panic 就要消耗好几天。

另一种就是 PetaLinux，它本质上是一个把 Yocto、设备树生成、启动引导配置、根文件系统打包、交叉编译工具链封装成一体的自动化工具链。它的设计目标很简单：输入的是厂商硬件设计导出文件（也就是 XSA），输出的是可以直接烧到板子上的 BOOT.BIN、image.ub 和 rootfs。这也就决定了安装环节的门槛：它不是一个双击安装完就结束的软件，而是你的整个嵌入式 Linux 构建流水线的地基。地基没打好，后面每一步都会跟着出问题。

1.2 版本怎么选：这是安装前最关键的决策

几乎所有人安装失败，都不是操作问题，而是版本不匹配。这里说的匹配包含三层意思：PetaLinux 版本和硬件设计工具版本要匹配；PetaLinux 版本和操作系统版本要匹配；SDK 版本和 PetaLinux 版本要匹配。

更具体的说，某版本的 PetaLinux 官方支持的操作系统列表是固定的，比如 Ubuntu 20.04、22.04 或者 CentOS 7 等。如果你用的是一个完全不在支持列表里的新系统，比如某个刚发布半年的最新发行版，那么最常出现的报错不是某个依赖缺失，而是 perl、tcl、gcc 等基础组件的版本和脚本预期不一致，导致安装到一半突然挂掉。

第三层匹配，也就是 SDK 的版本，实际上在安装 PetaLinux 时就已经决定了。PetaLinux 内部自带了一套完整工具链，文件系统、内核模块、U-Boot 全都用它来编。如果你安装之后要开发自己的应用程序，直接用这套工具链的交叉编译器即可。所以安装 PetaLinux 的过程，其实同时就是把 SDK 一起装了。这也是为什么这篇要把两个东西放在一起说，它们不是两个独立软件，而是一个整体。

我个人的建议是：除非你有特殊需求，否则不要追最新版。选一个从发布到现在超过半年的版本，这个版本的已知坑基本都被社区踩平了。如果手里的板子有官方提供的 BSP 包，那就直接以 BSP 对应的 PetaLinux 版本为准，这样最稳。

2. 环境准备与依赖处理

2.1 硬件资源和系统版本：别让你的电脑硬扛

安装 PetaLinux 对主机的资源要求，比一般软件要高不少。首先是磁盘空间。安装完基础工具和 SDK，占用通常在 100GB 以上，如果你的项目后面要 build 多个不同的镜像，还会继续膨胀。这个空间最好是 NVMe 固态盘，不是矫情，而是方案验证时动辄几十上百 GB 的文件拷贝，机械硬盘的耗时能把午饭时间全耗进去。

内存的话，8GB 是理论底限，但实际用起来会非常痛苦。在编译 kernel 或者跑 Yocto 任务时，内存不足会导致 OOM，进程被强制杀掉，构建中断。建议 16GB 起步，如果经常编译大型根文件系统，直接上 32GB。CPU 核心越多越好，因为大部分构建任务都是可以并行的。我自己用 8 核 16 线程的机器，一次完整构建大概需要一个半小时；换到 4 核的老机器，时间直接翻倍不止。

操作系统层面，最好准备一个干净的系统，不要在这一台机器上同时跑一大堆服务。如果你只有一台日常用的主力机器，也没关系，但至少保证空闲磁盘空间充足、没有奇怪的 shell 环境变量。

提示：安装路径不要带空格，不要放在中文目录下。这类自动化脚本对路径符号很敏感，空格和中文都可能导致难以排查的诡异错误。

2.2 依赖库清单和常见安装命令

Linux 主机上安装前的依赖库缺失，是新手最容易碰壁的地方。PetaLinux 的安装脚本会检查一部分依赖，但检查得并不全面，很可能你过了它的前置检查，实际使用时才发现缺少某个库。

下面这个依赖清单是根据 Ubuntu/Debian 系的常见包名整理的，不同的系统版本稍有差异，但整体思路一致：

sudo apt-get install -y \ gcc make build-essential \ libncurses-dev libssl-dev \ flex bison lib32z1 lib32ncurses6 \ iproute2 gawk xvfb gcc-multilib \ libtool autoconf automake \ tmux htop nfs-common \ screen xterm openssh-server \ zlib1g-dev libstdc++6 libstdc++6:i386 \ net-tools unzip device-tree-compiler

装完之后，建议顺手把 tftp 服务也装好并配置好，后面开发时通过网络加载镜像会频繁用到。

2.3 登录用户和目录结构：权限问题的根源

安装过程强烈建议不要用 root 用户直接操作，也不要用普通用户逐个文件加权限。最合理的做法是在系统里创建一个单独的开发者用户，比如叫，把这个用户加入 sudo 组，然后把所有工作放在这个用户的家目录下。

这样做的好处多多。第一，构建过程中生成的临时文件不会把权限搞得一团糟；第二，后面如果用 IDE 调试，用户权限统一了才能正常读写文件；第三，当团队多个账号同时使用时，避免互相覆盖。

目录结构也提前规划好。我常用的布局是这样的，供参考：

/opt/pkg/petalinux/ # PetaLinux 安装位置 /opt/pkg/xilinx/ # 硬件设计工具安装位置 ~/workspace/projects/ # 各项目目录 ~/workspace/downloads/ # 安装包和 BSP 文件

分这么细不是闲得慌。PetaLinux 构建过程中会生成大量中间文件，如果把安装目录和项目目录混在一起，失败清理时很容易误删关键文件。

3. 安装实操过程与核心环节

3.1 拿到安装文件和 BSP：下载阶段就该注意的事

安装 PetaLinux 的第一步，是去对应厂商官方页面下载安装器。这个过程看起来简单，实际上有几个需要留意的点。

首先，安装器体积不小，通常在 5GB 上下，下载时间取决于网络环境。下载时注意核对文件完整性和版本号。有的渠道会给一个 MD5 或者 SHA256 校验值，下载完成后先校验一把再开始安装，省得装到一半因为文件损坏报错。

其次，如果你有板卡对应的 BSP 文件，也一并下载好。BSP 文件通常只有几百 MB 到一两 GB，里面包含了板卡配置、设备树补丁、预编译的固件等，可以把很多环境的默认配置省掉。就算你不用 BSP，安装时也建议先手敲一个通用配置来验证安装环境，之后再引到具体板卡上。

拿到安装器之后，先授予执行权限，然后运行：

chmod +x petalinux-v2024.1-installer.run ./petalinux-v2024.1-installer.run --dir /opt/pkg/petalinux

运行之后会出现一个交互式的协议确认界面。如果你想跳过交互环节，可以加上--skip_license参数，但前提是你已经阅读并接受许可协议内容。这个脚本的安装时间和你机器的磁盘性能直接相关，一般情况下 20 分钟到 1 小时不等，装到一半不要因为看起来没反应就去 Ctrl+C。

3.2 配置环境变量和首次验证

安装完成之后，关键步骤是配置环境变量。PetaLinux 的脚本目录下有一个 setting 脚本，大概长这样：

source /opt/pkg/petalinux/settings.sh

注意这个命令必须在每个新的终端窗口里都执行一遍，否则petalinux-create、petalinux-build这些命令都找不到。如果觉得每次都手敲麻烦，可以把它写进~/.bashrc，但我个人不推荐，原因后面细说。

验证是否安装成功，最快的命令是这样的：

echo $PETALINUX petalinux-util --version

如果$PETALINUX变量能弹出安装路径，版本命令能正常输出，说明核心安装基本完成。

3.3 SDK 其实已经装好了，关键是怎么验证

很多人在装完 PetaLinux 之后到处找“SDK 安装按钮”，其实走错了方向。PetaLinux 安装完成后，工具链默认是完整的。这个 SDK 里最重要的几个部分是交叉编译器、sysroot 和一系列构建脚本。sysroot 就是你目标系统上的根文件系统的一个子集，里面包含了库文件和头文件，交叉编译出来的程序依赖这些库才能运行。

用简单的命令验证交叉编译器是否可用：

${PETALINUX}/components/yocto/sysroots/x86_64-petalinux-linux/usr/bin/aarch64-xilinx-linux-gcc --version

如果能输出版本信息，说明编译器链路是通的。这里要注意，上面路径里的aarch64-xilinx-linux是针对 ARM 64 位架构的，如果你的平台是 32 位 ARM，对应的编译器前缀不同。

3.4 用一个小Demo验证整个链路

安装验证不能只看版本号，强烈建议走通一个最小流程。用一个最简单的命令创建工程、构建镜像，这样才能确认工具链、配置、文件系统生成都是正常的。

创建一个测试工程：

petalinux-create --type project --template zynqMP --name test_proj

这里 template 根据你自己的硬件平台来选择，zynqMP是针对 Zynq UltraScale+ 系列的模板。创建完成之后，进入工程目录，然后运行构建：

cd test_proj petalinux-build

首次构建耗时取决于你的机器配置，通常在 30 分钟到 2 小时之间。构建成功的标志是最终生成了images/linux/目录下的 BOOT.BIN、image.ub 等文件。我第一次验证的时候，构建结束看到这几个文件，心里的石头才算落地了。

4. 安装和验证过程中最常见的报错

4.1 磁盘空间不足与目录结构引发的报错

这类报错最典型的表现是，安装或者构建过程中突然出现No space left on device，然后又带一小串文件名。很多人以为把根目录空间扩一下就好了，但实际上有可能问题出在你挂载点的大小上，或者 PetaLinux 的临时目录被指向了一个空间很小的分区。

排查方式很简单，构建前先看三个位置的空间：安装目录所在分区、/tmp所在分区、工程目录所在分区。这三个任意一个不够都会出问题。我个人的建议是直接把TMPDIR环境变量指到工程目录下的子目录，让所有临时文件都留在同一个分区里。

另外一个和目录相关的坑是，工程目录不要放在共享网盘或者 FUSE 挂载的文件系统上。文件锁、符号链接和权限模型都和本地文件系统不同，会在构建时引发未知错误，这类问题排查起来最费时间。

4.2 依赖缺失和版本不匹配的报错

最常见的一条报错大概长成这样：/bin/bash: tclsh: command not found。这个就是缺了 tcl 相关包。还有的报错是libtinfo.so.5: cannot open shared object file，这是 64 位系统和 32 位兼容库的问题。解决方案在 2.2 节的依赖清单里基本都覆盖了。

更隐蔽的问题是，系统自带的 Python 版本和 PetaLinux 不匹配。有的版本依赖 Python 3.8，有的系统默认带的是 3.10 甚至更高，这种时候不要用系统的 Python 去硬顶，也不要试图卸载系统自带的 Python 换个旧版本，会因为系统依赖被破坏。正确处理方式是读取 PetaLinux 官方文档里对 Python 版本的要求，然后用版本管理工具在特定目录下创建一个指定版本的 Python 环境，再把 PATH 指过去。

4.3 网络问题和下载中断

构建过程中 Yocto 会从网上下载不少源码包。如果网络不稳定或者镜像访问不通，最常见的表现是下载卡在某个进度反复重试。可以观察一个细节，如果同一个 URL 下载失败三次以上，那就要考虑是不是当前网络环境的问题，而不是单纯的重试能解决。

解决思路有两种。一种是利用离线下载模式，先把需要的源码包手动下载到一个共享目录中，构建脚本会自动优先检查这个目录。另一种方式则是遇事不决多试两次，Yocto 有断点续传机制，中断后重新执行构建命令，通常会接着下载未完成的部分，不用从头再来。但真的不要无限重试，如果一个包失败超过三次，优先考虑网络环境的根本问题。

4.4 环境变量污染导致的诡异行为

这是个很低调但折磨人的问题。某些同事或教程会把source settings.sh这行直接写进~/.bashrc，这样每次开终端都自动加载环境。但用户项目里的构建脚本、或者你自己手写的脚本里，如果修改了PATH、LD_LIBRARY_PATH这些全局变量，可能会把 PetaLinux 需要的环境依赖给覆盖掉。

最典型的例子是装了某个版本的 Anaconda，它会在.bashrc里把PATH前缀加上 conda 的路径，导致 PetaLinux 脚本找到的不是系统自带的 Python 而是 conda 那边的 Python。这个错误极其隐蔽，因为报错信息可能只是某个脚本说找不到模块或者版本不对，你不会第一时间想到是环境变量被污染。

处理方案：PetaLinux 环境变量只在构建时才 source，用完就开新的终端窗口。确实需要自动化构建时，在脚本里显式启动一个干净的 shell 环境来执行构建。我在实际项目中遇到过好几次类似的困扰，最后统一改成“每次构建在一个新的、干净终端里执行”，这类问题就很少再出现了。

4.5 SDK 交叉编译时找不到头文件和库文件

安装都正常、编译工具链也能运行，但自己写代码时偏偏找不到头文件，这是 SDK 使用中比较典型的问题。出现这个问题的原因几乎都是 sysroot 没指对，或者用户在编译命令里手工指定了宿主机的/usr/include。

sysroot 的正确用法，不是让编译器到宿主机上找头文件，而是让它去目标系统的根文件系统找。在 SDK 环境下，环境变量OECORE_NATIVE_SYSROOT和OECORE_TARGET_SYSROOT已经帮你设置好了。使用交叉编译器的时候，加上--sysroot=$OECORE_TARGET_SYSROOT参数，就能找到匹配目标平台的头文件和库文件。

CMake 用户可以直接使用 PetaLinux 生成的工具链文件，通常在工程目录的build/目录下找，用CMAKE_TOOLCHAIN_FILE指向它，路径、编译器、sysroot 都会自动配好。

5. 安装后的配置建议和生产力提升

5.1 多个项目建议用共享下载缓存

如果团队里有多个成员同时用同一套环境做开发，或者你要在同一台机器上维护多个 Petalinux 工程，那么设置共享的下载缓存会很实用，能显著减少重复下载源码包的时间。

在 PetaLinux 里，这个缓存机制直接读取 Yocto 的 DL_DIR 变量。最简单的方式是在你的~/.bashrc或者构建脚本里显式导出：

export DL_DIR=/opt/pkg/downloads

这个变量指定后，所有项目的源码下载都会先到这个目录找，找不到才会去网上下载。多项目之间共享这个目录之后，第一次构建可能会慢，但后续的构建会快不少，因为 kernel、u-boot、rootfs 的源码包都在本地了。

5.2 安装包也值得保留，升级回滚都有用

磁盘空间不紧张的话，安装器文件、BSP 文件这些其实都可以留着，不要装完就删。原因一是回滚需要，如果 PetaLinux 版本有问题想退回旧版本，手头有安装器就方便很多。原因二是团队要再加一台编译机器时，不用重新去官网下载。

另外 BSP 文件对应的构建缓存目录，也可以打包归档。换机器时把这些缓存解压到对应位置，能省去大量依赖包重新下载的时间。亲测在一台完全没有缓存的新机器上，用这个办法可以把首次构建时间缩短三分之一到一半。

5.3 做一次完整的镜像生成验证

安装完 PetaLinux 之后，给自己留一个最后的收尾仪式：用官方的 BSP 生成一个完整镜像试试水。注意这里不是只 run 到petalinux-build结束，而是要把镜像打包步骤也走完。

一条比较全能的验证命令是这个：

petalinux-package --boot --fsbl ./images/linux/zynqmp_fsbl.elf --u-boot --kernel

这一步会生成最终可烧录的 BOOT.BIN。如果你的环境能跑 QEMU 仿真，也可以直接用仿真模式启动做一遍最终验证。到这一步如果一切正常，说明你的安装是真的通了，而不是“看起来装了”。后面开发时构建失败才能定位到是代码问题而不是环境问题。

我个人在实际操作中的体会是，安装 PetaLinux 和 SDK 这事儿，真的不是熟能生巧，而是一次就要认认真真做对。每次图省事跳过依赖、跳过验证步骤，后面总是要加倍还回去的。上面这些坑，都是我用时间和精力换来的，你要是照着这份流程走一遍，不能说百分百顺利，但至少能绕开大多数一看就很挫败的坑。

最后再分享一个小技巧：安装时如果卡住不动了，不要只盯着终端发呆。打开另一个终端，用df -h看磁盘变化、用top看 CPU 和内存状态，多数情况下你就会发现它其实是在做密集的压缩或者解压，并没有死掉。学会判断“它是在干活”还是“真的挂了”，能让你少浪费很多等待的时间。