QEMU 官方文档、学习资源与参与贡献

官方文档

主站文档

主文档站在 QEMU 官方文档的 docs/master/ 路径下，按模块组织：

路径	内容
`docs/master/system/index.html`	全系统模拟（最重要）
`docs/master/user/index.html`	用户态模拟
`docs/master/tools/qemu-img.html`	qemu-img 完整参考
`docs/master/system/images.html`	磁盘镜像格式详解
`docs/master/system/monitor.html`	QEMU Monitor 命令
`docs/master/system/introduction.html`	架构与加速器介绍

读文档的建议：先读 Introduction 搞清楚架构，再看 System Emulation 的 Quick Start，然后按需深入具体模块。

QEMU Wiki

wiki.qemu.org 是社区维护的补充知识库：

Features 页面：wiki.qemu.org/Features/
Guest OS 列表：wiki.qemu.org/Hosts/
已知问题：wiki.qemu.org/KnownIssues

man page

每个 QEMU 命令行工具都有 man page：

man qemu-system-x86_64
man qemu-img
man qemu-nbd
man qemu-io
man qemu-pr-helper

man page 是命令行参数最权威的参考——但内容很长，建议配合 --help 一起用。

中文学习资源

官方中文文档

QEMU 主站文档有部分中文翻译（docs/master/zh_CN/），但覆盖不全。

社区资源推荐

来源	类型	说明
ArchWiki QEMU 条目	Wiki	中文 ArchWiki 的 QEMU 条目质量很高
Debian Wiki QEMU	Wiki	Debian 上 QEMU 的配置与使用
SUSE 虚拟化指南	文档	完整的 QEMU/KVM 部署指南
Red Hat 虚拟化指南	文档	RHEL 上 KVM 的完整参考
GitHub awesome-qemu	列表	QEMU 相关资源汇总

英文深入资源

来源	类型	说明
QEMU Wiki Features	Wiki	所有功能点的说明
QEMU ChangeLog	日志	每个版本的新特性列表
QEMU mailing list archives	邮件	开发讨论的完整档案
virtio-spec 仓库	规范	VirtIO 协议标准文档

常见问题去哪里问

先查文档

问题 90% 在主文档和 Wiki 里已有答案。搜索建议关键词：

QEMU + 你的问题关键词
例: QEMU Windows guest virtio driver
例: QEMU nested virtualization

社区

渠道	适用
QEMU mailing list（qemu-devel）	开发讨论、补丁审查
QEMU mailing list（qemu-users）	用户问题、使用帮助
StackOverflow [qemu] 标签	具体技术问题
Reddit r/qemu	社区闲聊、新手问题
GitHub Issues	Bug 报告、功能请求

报告 Bug

收集信息

报告 Bug 之前，先收集这些信息：

# QEMU 版本
qemu-system-x86_64 --version

# 宿主 OS 和版本
uname -a          # Linux
sw_vers           # macOS
systeminfo        # Windows

# QEMU 命令行（去掉敏感信息）
echo $QEMU_COMMAND

# Guest OS
# 启动日志、内核 panic 截图等

报告渠道

GitHub Issues（优先）：github.com/qemu/qemu/issues
邮件列表：qemu-devel@nongnu.org

格式：标题概括问题，正文附复现步骤 + 命令行 + 预期 vs 实际。

参与开发

准备环境

git clone https://gitlab.com/qemu-project/qemu.git
cd qemu
./configure
make -j$(nproc)

开发者文档

docs/devel/ 下有完整的贡献指南：

docs/devel/submitting-a-patch.rst：提补丁流程
docs/devel/coding-style.rst：代码风格
docs/devel/trivial-patches.rst：简单补丁列表（新手友好）

第一次贡献建议

从 trivial patches 列表挑一个小任务
读完提交指南（submitting-a-patch.rst）
写好代码，本地跑测试
用 git format-patch 生成补丁，发邮件到 qemu-devel

CI 和测试

QEMU 有完整的 CI：GitLab CI + Buildkite。补丁发到邮件列表后会自动跑测试，测试报告邮件通知作者。

配套工具

工具	用途
`virt-manager`	图形管理前端（libvirt 生态）
`virsh`	libvirt 命令行管理
`qemu-img`	磁盘镜像操作
`qemu-nbd`	把 qcow2 镜像暴露为 NBD 块设备
`qemu-io`	对镜像直接做 I/O 测试
`qemu-strace`	用户态模拟里看 syscall
`SPICE client`	远程图形访问
`OVMF`	UEFI 固件（替代 SeaBIOS）
`virtio-win`	Windows Guest 的 VirtIO 驱动

生态项目

项目	关系
libvirt	QEMU 的管理守护进程（最常用）
Proxmox	基于 Debian + QEMU/KVM 的完整虚拟化平台
Kata Containers	基于 QEMU 的轻量级容器
Firecracker	AWS 基于 QEMU 的 microVM
Cloud Hypervisor	Rust 重写的轻量 QEMU 分支
UTM	基于 QEMU 的 macOS/iOS GUI 前端
Box86/Box64	独立的 x86→ARM 翻译器（不是 QEMU 分支）

许可证

QEMU 各部分许可证不同：

系统模拟核心：GPL v2
用户态模拟：LGPL v2
部分前端（TCG）：BSD
网站资源：CC BY-SA

完整许可证清单见 COPYING 文件和 docs/license.rst。

下一步

这是本站最后一页。回到首页或跳去任何你感兴趣的分组继续学习。

QEMU 是一个庞大的开源社区项目，保持好奇、多做实验、遇到问题先搜文档，祝你玩得开心。