Windows、macOS、liunx下使用qemu搭建riscv64/linux

背景

在Windows、macOS和Linux环境下使用QEMU搭建RISC-V 64位Linux系统，网络上存在大量过时、不完整或错误的教程。且部分AI生成的内容"幻觉"现象严重，导致关键步骤错误且难以进行。为确保可靠性，本教程基于最新实测验证，涵盖三种操作系统环境，并以Casibase项目作为下游任务进行了搭建部署，如果读者需要在riscv64部署、运行golang + react + mysql服务，可以参考下篇文章。

所有必要工具及文件的下载链接均来自官方源，避免因第三方托管导致的版本混乱或安全风险。以下内容经过完整测试，确保从环境配置到系统启动的每一步均可复现。

关于Casibase

介绍：⚡️AI Cloud OS: Open-source enterprise-level AI knowledge base and MCP (model-context-protocol)/A2A (agent-to-agent) management platform with admin UI, user management and Single-Sign-On⚡️, supports ChatGPT, Claude, Llama, Ollama, HuggingFace, etc., chat bot demo: https://ai.casibase.com, admin UI demo: https://ai-admin.casibase.com

GitHub仓库：https://github.com/casibase/casibase

官网：casibase.org

目标

分别在Windows、macOS、liunx下使用qemu搭建基于Debian的riscv64/linux系统。

我们需要三个必要的软件：

• QEMU
• OpenSBI：一个开源项目：RISC-V Open Source Supervisor Binary Interface，SBI 是在 RISC-V 模式运行的硬件和操作系统之间的层，有点类似 BIOS。
• U-Boot：一个开源的主引导加载程序，提供一系列用于引导操作系统内核的指令。

环境部署

一、Windows

1. 从官网下载QEMU

Download QEMU - QEMU 该下载链接简短清晰，阅读后直接下载即可。

2. 下载 OpenSBI 和 U-Boot

无需源码构建（复杂），直接从 De­bian Archive 中下载预编译的版本即可。

• OpenSBI：Debian -- Details of package opensbi in sid
• U-Boot：Debian -- Details of package u-boot-qemu in sid

下载会得到两个 .deb 软件包。这是Debian系统的软件包文件，我们仅需要内部的fw_jump.elf和uboot.elf文件。所以，只需要解压出这个.deb文件即可。

Windows下可以使用第三方解压软件，如7-Zip等。解压后，继续解压data.tar.xz文件，形成usr目录。之后按路径：basePath \usr\lib\riscv64-linux-gnu\opensbi\generic\fw_jump.elf和basePath\usr\lib\u-boot\qemu-riscv64_smode\uboot.elf拿到对应要的文件（可以迁移到任何位置，并不依赖当前包下其他文件起作用）。

3. 下载riscv64 QCOW2 虚拟磁盘。

不需要自己去构建，直接使用Debian Quick Image Baker pre-baked images预编译镜像：Debian Quick Image Baker pre-baked images 下载 Release architectures---->Images for riscv64-virt项。下载后是一个无后缀的文件，将其重命名为zip后缀，然后解压。得到关键文件：image.qcow2

至此，结束前期准备，可以启动qemu riscv64了。请翻阅文末。

二、Linux

前言：qemu可从官网下载，OpenSBI、 U-Boot、QCOW2并不吃操作系统差异，所以即使按照window的配置流程进行也完全没问题，只不过命令有差异而已。但是如Linux/macOS这类操作系统的包管理命令（apt、yum）可以很方便帮我们完成上述工作（缺点：包比较老旧，但是实测可用，未发生不兼容情况）。所以下文以Debian/ubuntu为例进行：

0. 安装依赖包：

sudo apt-get install build-essential pkg-config libboost-all-dev autoconf libtool libssl-dev flex bison ninja-build libglib2.0-dev    libpixman-1-dev libslirp-dev libncurses5-dev libncursesw5-dev 

1. 下载QEMU

Arch: pacman -S qemu

Debian/Ubuntu:
For full system emulation: apt-get install qemu-system
For emulating Linux binaries: apt-get install qemu-user-static
Fedora: dnf install @virtualization

Gentoo: emerge --ask app-emulation/qemu

RHEL/CentOS: yum install qemu-kvm

SUSE: zypper install qemu

验证：qemu-system-riscv64 --version

2. 下载 OpenSBI 和 U-Boot

sudo apt update
sudo apt install qemu-system-misc opensbi u-boot-qemu

3. 下载riscv64 QCOW2 虚拟磁盘。

不需要自己去构建，直接使用Debian Quick Image Baker pre-baked images预编译镜像：Debian Quick Image Baker pre-baked images 下载 Release architectures---->Images for riscv64-virt项。下载后是一个无后缀的文件，将其重命名为zip后缀，然后解压。得到关键文件：image.qcow2：

# 下载镜像
wget -O dqib_riscv64-virt.zip "https://gitlab.com/api/v4/projects/giomasce%2Fdqib/jobs/artifacts/master/download?job=convert_riscv64-virt"

# 重命名并解压
unzip dqib_riscv64-virt.zip

# 显示文件列表
ls -la

至此，结束前期准备，可以启动qemu riscv64了。请翻阅文末。

三、MacOS

前言：qemu可从官网下载，OpenSBI、 U-Boot、QCOW2并不吃操作系统差异，所以即使按照window的配置流程进行也完全没问题，只不过命令有差异而已。但是如Linux/macOS这类操作系统的包管理命令（apt、yum、brew）可以很方便帮我们完成上述工作（缺点：包比较老旧，但是实测可用，未发生不兼容情况）。所以下文以Debian/ubuntu为例进行：

1. 下载QEMU

brew install qemu

验证：qemu-system-riscv64 --version

2. 下载 OpenSBI 和 U-Boot

无需源码构建（复杂），直接从 De­bian Archive 中下载预编译的版本即可。

• OpenSBI：Debian -- Details of package opensbi in sid
• U-Boot：Debian -- Details of package u-boot-qemu in sid

下载会得到两个 .deb 软件包。这是Debian系统的软件包文件，我们仅需要内部的fw_jump.elf和uboot.elf文件。所以，只需要解压出这个.deb文件即可。

MacOS下可以使用"ar -x 文件名"进行解压。解压后，继续解压data.tar.xz文件，形成usr目录。之后按路径：basePath \usr\lib\riscv64-linux-gnu\opensbi\generic\fw_jump.elf和basePath\usr\lib\u-boot\qemu-riscv64_smode\uboot.elf拿到对应要的文件（可以迁移到任何位置，并不依赖当前包下其他文件起作用）。

3. 下载riscv64 QCOW2 虚拟磁盘。

不需要自己去构建，直接使用Debian Quick Image Baker pre-baked images预编译镜像：Debian Quick Image Baker pre-baked images 下载 Release architectures---->Images for riscv64-virt项。下载后是一个无后缀的文件，将其重命名为zip后缀，然后解压。得到关键文件：image.qcow2：

# 下载镜像
wget -O dqib_riscv64-virt.zip "https://gitlab.com/api/v4/projects/giomasce%2Fdqib/jobs/artifacts/master/download?job=convert_riscv64-virt"

# 重命名并解压
unzip dqib_riscv64-virt.zip

# 显示文件列表
ls -la

至此，结束前期准备，可以启动qemu riscv64了。请翻阅文末。

四、启动

建议把前期的四个工具的文件都整到一起，便于管理（qemu、OpenSBI、 U-Boot、QCOW2）

qemu riscv64/linux启动命令：

qemu-system-riscv64 -machine virt -m 8G -smp 8 -cpu rv64 \
-device virtio-blk-device,drive=hd \
-drive file=image.qcow2,if=none,id=hd \
-device virtio-net-device,netdev=net \
-netdev user,id=net,hostfwd=tcp::2222-:22,hostfwd=tcp::14000-:14000 \
-bios ～/riscv-linux/opensbi-1.3-rv-bin/share/opensbi/lp64/generic/firmware/fw_dynamic.elf \
-kernel ～/riscv-linux/usr/lib/u-boot/qemu-riscv64_smode/uboot.elf \
-object rng-random,filename=/dev/urandom,id=rng \
-device virtio-rng-device,rng=rng \
-nographic -append "root=LABEL=rootfs console=ttyS0"

注意：

1. -drive file参数，后面跟着的是QCOW2的image.qcow2文件。注意路径要正确。

2. -bios 参数，后面跟着的是opensbi的elf文件。注意路径要正确。

3. -kernel参数，后面跟着的是u-boot的elf文件。注意路径要正确。

4. 第一行-m、-smp参数，后面跟着的分别是内存和核心数，要根据自己电脑配置来，不然启动会失败，建议不要吝啬，因为qemu本身把riscv命令变为❌86等命令就很耗时，再加上riscv架构上许多应用适配不好，进一步加剧性能损耗，不加大内存和核心数的话很容易卡死riscv系统。

5. -netdev参数，后面跟着的是要映射的主机端口，因为riscv和本机默认是NAT方式。如果我们希望riscv中的某些端口可以被外界访问，那么就需要配置映射，例如，本例中增加了14000作为映射端口，希望可以在宿主机使用localhost:14000的方式访问riscv服务。（建议保留2222-：22的映射）。

6. 此外的报错，碰见缺啥依赖包下载啥就行了，都是包管理工具直接下载的包。

四、补充

下载下来的riscv64 QCOW2 虚拟磁盘默认是10G大小，很多情况下根本不够用。如果未来出现问题，可以进行扩容：

1. 进入到image.qcow2所在文件夹下，执行：

qemu-img resize image.qcow2 +10G

2. 扩容

# 更新包列表
sudo apt update

# 安装cloud-guest-utils包（包含growpart工具）
sudo apt install cloud-guest-utils

# 查看磁盘分区
sudo fdisk -l

# 扩展第一个分区到最大可用空间
sudo growpart /dev/vda 1

# 验证分区是否扩展成功
sudo fdisk -l /dev/vda

# 检查文件系统类型
df -T /

# 如果是ext4文件系统
sudo resize2fs /dev/vda1

# 如果是xfs文件系统
sudo xfs_growfs /

# 验证扩展结果
df -h /