PS2 Web Recomp 详解与上手教程

想在浏览器里重玩《GT4》或《战神2》？PS2 Web Recomp 的作者已经把这两款游戏跑进了 Chrome：GT4 能上赛道，战神2 能进入战斗，声音、手柄和存档也有了。

想自己试，入口在官方 GitHub 仓库，里面也有作者的演示。你需要下载工具，用自己拥有的游戏镜像生成本地游戏网页，再从浏览器启动。第一次仍要安装和构建，项目没有提供点开就能玩的在线游戏页。

可以先确认你的电脑和系统要求，再跟着安装、构建步骤操作；已经有生成好的网页文件，可以直接看启动方法。

PS2 Web Recomp 现在能玩到哪一步

截至 2026 年 10 月 16 日，作者重点展示了《Gran Turismo 4》和《God of War II》。作者报告的浏览器表现分别是：GT4 的 PAL 版本在两倍内部分辨率下达到 50 FPS；战神 2 在原生分辨率的战斗场景达到 60 FPS。这些数字对应作者的 Chrome 和集成显卡笔记本环境。项目说明

第一次尝试时，优先选择自己拥有、且已有项目记录的游戏。游戏地区、版本和场景都可能影响结果；进入标题画面以后，还要检查实际游玩、声音和保存进度。

它与名称接近的 ran-j/PS2Recomp 是不同项目。后者面向原生 PC 移植；本文的命令只适用于 snuri00/ps2-web-recomp。搜索下载入口时认准仓库所有者和完整名称。

开始前选择适合自己的系统

完成一次尝试需要三样东西：构建工具、自己拥有游戏的光盘镜像，以及能运行生成页面的浏览器。构建在本机进行，首次还会下载工具链，需要网络和额外磁盘空间。为镜像、SDK、编译缓存留出数 GB 余量；解压镜像还会额外占用空间。

上游记录的构建平台是 Linux x86-64 和 Apple Silicon macOS。浏览器端优先使用更新后的桌面 Chrome 或 Edge。平台说明

项目代码采用 MIT 许可证，但仓库不包含游戏。作者要求使用自己拥有游戏的镜像，并将生成的游戏代码和构建产物留在自己的电脑上。不要把镜像、生成的 C++ 或带游戏内容的网页上传到公开仓库、网盘或网站。项目的使用说明

第一步 安装构建工具

下面的代码块在终端中运行，一次复制一块，按 Enter 执行。只复制代码，不要添加提示符 $。安装时若询问系统密码，输入过程通常不显示字符，输完按 Enter 即可。出现错误时先停下来处理，不要继续粘贴下一块。

Ubuntu 24.04

打开“终端”，先确认系统和处理器：

lsb_release -ds
uname -m

这一分支对应 Ubuntu 24.04 和 x86_64。安装所需工具：

sudo apt update
sudo apt install git cmake ninja-build clang-18 \
  libc++-18-dev libc++abi-18-dev build-essential \
  python3 curl unzip libvulkan1

这里指定 Clang 18，避免系统恰好选中太旧的编译器。Ubuntu 24.04 提供对应的软件包。图形驱动仍使用你电脑正常配置的驱动，不要为这篇教程卸载或替换现有驱动。

继续检查：

git --version
cmake --version
ninja --version
clang++-18 --version
python3 --version
export CXX=clang++-18

每条版本命令都应显示版本号；CMake 至少需要 3.20。export 没有输出是正常现象，它只为当前终端指定编译器。构建配置

如果 apt 提示找不到包，先核对系统版本和软件源。不要把 Ubuntu 命令直接粘进 Windows PowerShell。

Apple Silicon Mac

在“应用程序 → 实用工具”中打开“终端”。运行 uname -m 应显示 arm64。先安装 Apple 命令行工具：

xcode-select --install

已经安装时会收到相应提示，可以继续。尚未安装 Homebrew 的读者，从 Homebrew 官方安装说明进入，完成安装及页面要求的 PATH 设置，再检查 brew --version。

brew install bash cmake ninja python llvm
export PATH="$(brew --prefix)/bin:$(brew --prefix llvm)/bin:$PATH"
export CXX="$(brew --prefix llvm)/bin/clang++"
bash --version
cmake --version
ninja --version
python3 --version
"$CXX" --version

检查 Bash 的主版本应为 4 或更高；macOS 自带的 Bash 3.2 不够。PATH 和 CXX 的设置只作用于当前终端，第一次构建过程中请保留这个窗口。新版 Bash 要能被子脚本找到，因此只把外层命令改成 bash scripts/port.sh 还不够。

第二步 下载项目并准备镜像

建立独立的教程目录

在刚才的终端执行：

mkdir -p "$HOME/ps2-web-guide"
cd "$HOME/ps2-web-guide"
git clone https://github.com/snuri00/ps2-web-recomp.git
cd ps2-web-recomp
git switch --detach c628ae843209f6e4cef34ec04efb6267a1618882
git rev-parse --short HEAD

最后应显示 c628ae8。这是本文核对的源码版本，固定它可以让命令、界面和排错说明对应起来。detached HEAD 是固定版本时的正常提示。若目录已经存在，保留原目录，换一个新的教程目录开始。

Mac 用户在这个版本上还需要处理一次编译器名称检测：脚本会寻找带版本号的 clang++ 命令，只有无版本名称时可能提前退出。下面在教程目录里创建一个指向 Homebrew 编译器的链接，不修改系统编译器：

mkdir -p .guide-bin
ps2_clang_major="$("$CXX" -dumpversion | cut -d. -f1)"
if [ ! -e ".guide-bin/clang++-$ps2_clang_major" ]; then
  ln -s "$CXX" ".guide-bin/clang++-$ps2_clang_major"
fi
export PATH="$PWD/.guide-bin:$PATH"

这个问题也出现在社区的修复记录中。Ubuntu 分支已经安装了 clang++-18，无需这一步。

用一个清楚的路径放置 ISO

mkdir -p "$HOME/ps2-discs"

使用文件管理器，把自己的 ISO 放进个人目录下的 ps2-discs 文件夹。例如文件名是 My Game.iso，检查它是否存在：

ls -lh "$HOME/ps2-discs/My Game.iso"

把 My Game.iso 替换为实际文件名，保留两侧英文双引号；双引号用于保护路径中的空格。看到文件大小和路径后再继续。若提示找不到文件，核对大小写、扩展名和文件夹位置。

首轮使用单独的 .iso 更容易排错。脚本也接受包含 ISO 的 ZIP 和 7z，但其他格式不能靠改扩展名变成 ISO。7z 路线还需要能执行 7z 命令的工具。镜像处理脚本

第三步 安装工具链并构建游戏

先单独完成工具链准备

确认当前目录里能看到 scripts、runtime 和 CMakeLists.txt：

pwd
ls
./scripts/setup.sh

首次运行会下载 Emscripten SDK 和 wgpu-native，并构建两个转换工具。本文对应脚本固定使用 Emscripten 6.0.11；不必另找一个最新 SDK 手工替换。已有 EMSDK 环境变量会改变 SDK 位置。初始化脚本

正常结束时会看到 == ready。然后检查文件：

ls build/tools/eerecomp build/tools/vurecomp

如果下载或编译失败，保留终端中第一条错误及前后几行，先处理它。不要用 sudo 重新运行整个项目来碰运气。

把镜像转换成网页构建

./scripts/port.sh mygame "$HOME/ps2-discs/My Game.iso"

mygame 是你给这份构建起的短名称。第一次照用这个名称即可；本文后续目录和启动命令都与它配套。更换游戏或光盘版本时使用新的名称，例如 mygame-pal，避免沿用旧镜像链接和探索数据。只改文件路径、继续复用同一个名称，可能仍然读到上一次的镜像。

终端中的阶段标记来自构建脚本：

探索阶段会自动尝试按键，画面不一定弹出独立窗口。部分编译输出写入日志，终端暂时安静也不能单凭这一点判断卡死。首次下载、电脑性能和游戏差异都会影响等待时间。

构建结束后检查：

ls build/web-mygame/ps2web.html
ls build/web-mygame/ps2web.js
ls build/web-mygame/ps2web.wasm
ls build/web-mygame/ps2web.data

这四个文件来自网页构建步骤。同时打开 games/mygame/shots 看探索截图，再查看 games/mygame/explore.log。文件编译成功与游戏走到可玩场景是两个检查点。

第四步 启动本地网页

仍在项目根目录运行：

python3 scripts/serve.py build/web-mygame games/mygame/disc.iso

看到 serving 和本机地址后，保留终端窗口，在同一台电脑的 Chrome 或 Edge 地址栏输入：

http://127.0.0.1:8620/

地址要包含 http://，不要把它输入搜索框。等待页面的 Loading… 变成可点击的 Start，点击后进入游戏。以后都使用同一个地址，方便找到相同的浏览器存档。

不要双击 ps2web.html，也不要改用普通的 python3 -m http.server。项目的专用服务器会提供共享内存需要的隔离响应头，以及读取光盘内容的 Range 请求。本文固定版本默认只监听 127.0.0.1；不用开放路由器端口或搭建公网服务。

如果 8620 已被其他程序占用，可以换端口：

python3 scripts/serve.py build/web-mygame games/mygame/disc.iso 8621

浏览器地址相应改成 http://127.0.0.1:8621/。换端口会改变浏览器存储所属的地址，已有进度先导出再迁移。

第五步 操作游戏并保存进度

键盘和手柄

页面点击 Start 后，游戏里的开始键仍然是 Enter。按键名称和游戏提示分开看，尤其是使用圆圈确认的游戏。

手柄连接电脑后，回到游戏页面按一下手柄按钮，再检查游戏是否响应。先从一倍内部分辨率开始，确认正常游玩后再提高。切换分辨率会重新加载页面，先在游戏内存档。界面与输入实现

保存与导出记忆卡

先在游戏内部执行存档；游戏若要求格式化一张全新记忆卡，按其提示完成。页面会把记忆卡写入浏览器存储。退出前点击 Export card，把下载的 .ps2 文件保存到容易找到的位置，例如“文稿”里的游戏备份文件夹。

换浏览器、换端口或换电脑时，先备份目标浏览器已有的卡，再用 Import card 导入备份。导入会替换当前卡并重新加载页面。当前实现接收 8 MB PS2 记忆卡对应的原始镜像布局，检查文件大小为 8,650,752 字节；单个游戏的存档文件不能直接当作整张记忆卡导入。记忆卡实现

普通窗口、相同浏览器用户配置和相同地址有助于持续找到存档。localhost 与 127.0.0.1 是不同主机名，8620 与 8621 是不同端口；无痕窗口和清除网站数据也会影响保存的内容。多款游戏如果共用同一个地址，也应分别导出并清楚命名备份。

关闭以后下次怎么开

游戏内存档并导出备份后，关闭游戏标签页，回到运行服务器的终端按 Control+C。终端恢复到可以输入命令的状态，说明服务已经停止。

下次只需要：

cd "$HOME/ps2-web-guide/ps2-web-recomp"
python3 scripts/serve.py build/web-mygame games/mygame/disc.iso

然后打开相同的浏览器地址。工具链安装和游戏构建都无需每天重做。保留原 ISO 的位置，因为构建目录中的镜像可能只是指向它的链接。

出错时按症状排查

先区分安装错误和游戏兼容问题

• 提示 command not found：找到报错点名的命令，回到对应系统的安装步骤。重新打开终端后，也要检查 PATH 是否仍指向已安装的工具。
• 提示 bad substitution，或 Bash 仍是 3.2：Mac 可能仍在调用系统旧 Bash。重新执行 Homebrew PATH 设置，再运行 bash --version。
• 提示 no C++ compiler here has <format>：检查编译器和 C++ 标准库是否完整。Ubuntu 核对 Clang 18 及 libc++ 包；Mac 核对 LLVM 和 Apple 命令行工具。
• 工具链下载失败：保留 GitHub 或 SDK 下载输出中的具体错误，恢复网络后重跑 setup.sh。不关闭 TLS 校验，不改用来历不明的构建包。
• 找不到 ISO 或 SYSTEM.CNF：核对路径、文件格式和镜像内容。不要只改扩展名；换用正确镜像后，也要使用新的构建名称。
• 编译中断：找最早一条错误，并查看原生编译日志 build/native-mygame/ninja.log。按错误补依赖；若进程被系统因内存不足终止，关闭其他高占用程序后再试。
• 网页显示 Unsupported browser：查看页面列出的缺失功能，更新桌面 Chrome/Edge，并确认通过项目服务器访问。
• 网页打不开，或资源返回 404：确认服务器终端仍在运行，回到项目根目录重新启动，核对端口和四个网页文件。
• 菜单能进，但 3D 极慢：查看状态文字是否出现 software renderer。检查 WebGPU、图形驱动与一倍分辨率；软件回退不适合重负载 3D。
• 游戏总卡在同一位置：查看探索日志是否出现 [sys] unhandled syscall 或 [iop] missing，保存游戏版本、截图和日志。这是运行时兼容问题的线索，重复安装工具通常无济于事。
• 有画面没声音：确认已经点击 Start，检查标签页和系统音量，再查看游戏或音频报错。持续静音也可能来自游戏适配缺口。
• 存档突然不见：核对浏览器配置、主机名和端口是否改变。回到原地址导出，或导入之前备份的 .ps2 卡。

页面还会检查共享内存、JSPI、WebAssembly 异常处理、尾调用和 SIMD；仅看到“WebGPU 可用”不能代替完整检查。浏览器能力检查

Linux 上若页面提示 WebGPU 不可用，上游给出的实验选项是 chrome://flags/#enable-unsafe-webgpu 与 chrome://flags/#enable-vulkan。这些是浏览器实验设置，应只在专用测试配置中按需调整，重启后复查，并在结束后恢复；不需要关闭浏览器沙箱或网站隔离。上游浏览器说明

探索没有进入游戏时检查按键

默认探索会自动发送 Start 和叉键。若游戏在菜单要求按圆圈，可以在新的构建名称下指定输入，例如：

./scripts/port.sh mygame-circle "$HOME/ps2-discs/My Game.iso" \
  --frames 7200 \
  --press 300:start --press 600:circle --press 900:circle

--press 前面的数字是探索帧号；添加自定义输入后会替换默认按键序列，需要把所有想要的输入一起写出来。这个例子只是检查另一条菜单路径，无法补齐未实现的硬件功能。看 games/mygame-circle/shots 和日志判断结果。参数定义

需要求助时，可以使用故障记录模板。保留系统、源码版本、游戏地区/版本、完整命令和第一条错误；分享前去掉私人路径，不附上 ISO 或游戏生成代码。

Windows 与 WSL 怎么处理

Windows 读者可以先用 PowerShell 的 wsl --status 和 wsl --list --verbose 查看现有环境。尚未安装时，按 Microsoft 的 WSL 安装文档准备 Ubuntu，系统可能需要管理员权限和重启；进入 Ubuntu 后才使用本文的 Linux 命令。

WSL 在这里属于探索路线。原生探索程序、图形后端和浏览器访问都需要分别检查，上游当前没有给出完整的 Windows／WSL 成功流程。尤其不要把某个 PS2Recomp.exe 当成本文项目的 Windows 版，也不要把在 Windows Chrome 里看到演示等同于在 Windows 上完成了构建。

PS2 游戏为什么能在网页里运行

这条路线先处理游戏的机器码。转换器分析控制流，把主处理器执行的操作写成 C++；Emscripten 再将生成代码与运行时编译为 WebAssembly。浏览器执行这份程序，运行时补上游戏预期的系统调用、内存与硬件行为。构建配置

WebAssembly 承担计算和执行，WebGPU 提供 GPU 计算与绘图接口。项目用计算着色器重建 PS2 图形芯片的绘制行为，其他部件仍需模拟。因而“静态重编译”与“硬件模拟”会同时出现在这个项目中。WebAssembly 的设计目标与 WebGPU 文档解释了这两个浏览器能力的分工。

预先分析仍会漏掉部分间接跳转目标，因此构建脚本要探索运行、记录新入口、再次转换。探索经过的场景有限，后续关卡可能触发新的路径。这也解释了为什么教程里要分别检查“构建结束”和“实际可玩”。

性能优化同样发生在具体环节。作者记录过把每帧 GPU 计算调度从约 650 次降到约 80 次的过程：在保证依赖关系正确的前提下重排上传，减少批次被拆散。这类开销对画面内容没有直接贡献，却会挤占每一帧的预算。优化记录

接下来值得关注的进展

新增游戏能带来新的检验场景。社区的《Kingdom Hearts II》提案记录了启动、菜单和开场演出，也明确保留背景音乐与后续游玩的工作；截至本文核验时，该提案尚未合并。社区移植记录。《GT3》的另一项提案也处于实验阶段，不能直接加入主分支兼容游戏清单。GT3 提案

对普通玩家，更容易安装、更清楚的兼容信息和更可靠的存档体验会直接降低尝试成本。对开发者，代码如何转换、浏览器怎样处理资源与线程、一个新游戏如何暴露旧问题，都有继续追踪的价值。

如果你也想制作一个能通过链接分享的原创小游戏，可以接着看零编程基础制作第一个可玩游戏；已经有原型、卡在故障上时，用截图和复现步骤排查游戏 Bug可以接着用。