如何从源码构建 Silent Hill PC 移植版:CMake+Ninja+MSYS2 完整编译教程与常见错误排查

原创2026-10-28 14:14:471,683 阅读

如何从源码构建 Silent Hill PC 移植版:CMake+Ninja+MSYS2 完整编译教程与常见错误排查

本文教你用 CMake + Ninja + MSYS2(MinGW-w64)从零构建 Silent Hill PC 移植版(silent-hill-decomp):一个基于 PSX 反编译的《寂静岭1》原生 PC 移植项目。它不是模拟器,而是直接用反编译出的 C 源码编译出真实的 Windows 可执行文件,支持任意分辨率、宽屏、高刷新率与 Mod。下面给出完整的从源码构建步骤,并逐一排查最常见的编译错误。

Silent Hill PC 移植版构建产物 SilentHillPC_Launcher 启动器界面

构建前先了解项目结构

整个仓库由两部分组成,理解它们能帮你读懂绝大多数报错:

目录 作用
src/、include/ 原 PSX 反编译的游戏代码(主程序、BODYPROG 引擎、42 个地图覆层)
pc_port/ PC 移植层:入口、图形/音频适配、启动器、CMake 构建系统
pc_port/PsyCross/ Git 子模块,PSY-Q 硬件抽象层(SDL2 + OpenGL + OpenAL)

构建入口是 pc_port/CMakeLists.txt:它要求 CMake 3.16+,默认 CMAKE_BUILD_TYPE=RelWithDebInfo,并全局强制位置无关代码(CMAKE_POSITION_INDEPENDENT_CODE),因为地图覆层要编译成 DLL。

环境准备:MSYS2 依赖安装清单

🛠️ 官方推荐的 Windows 构建环境是 MSYS2 + MinGW-w64 + Ninja(请勿使用 Visual Studio 生成器)。

  1. 安装 MSYS2,然后打开 “MSYS2 MinGW x64” 终端(注意:不要用 32 位的 MSYS shell);
  2. 一键安装工具链与依赖库:
pacman -S --needed mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake \
    mingw-w64-x86_64-ninja mingw-w64-x86_64-SDL2 \
    mingw-w64-x86_64-openal mingw-w64-x86_64-libjpeg-turbo
  • mingw-w64-x86_64-SDL2:窗口与输入(CMake 通过 find_package(SDL2) 查找)
  • mingw-w64-x86_64-openal:3D 音效
  • mingw-w64-x86_64-libjpeg-turbo:FMV 视频的 MJPG 解码
  • 可选:mingw-w64-x86_64-ffmpeg(开发头文件),启用 SH_FMV_FFMPEG 后支持 mp4/mkv/webm 影片替换
  1. 克隆仓库并初始化 PsyCross 子模块(必须,否则 CMake 直接 FATAL_ERROR):
git clone https://gitcode.com/gh_mirrors/sil/silent-hill-decomp.git
cd silent-hill-decomp
git submodule update --init --recursive
  1. 准备游戏光盘镜像(BIN 转储,需合法来源),放到:
pc_port/build/gamedata/Silent Hill (USA).bin

方式一:build.bat 一键构建(推荐新手)

pc_port/build.bat 是官方 Windows 构建脚本,双击会出现菜单:

选项 作用
1 增量构建(首次会自动用 Ninja + 地图 DLL 模式配置)
2 干净重建(cmake --build --clean-first)
3 构建并运行游戏
4 仅启动已构建的 exe
5 重新执行 CMake 配置后构建
6 清空构建目录(保留 gamedata/save/config.cfg)

命令行模式:build.bat / build.bat rebuild / build.bat run / build.bat nuke。

⚠️ 两个内置检查:找不到 C:\msys64\usr\bin\bash.exe 时,可先设置自定义路径,如 set MSYS2_ROOT=D:\msys64 && build.bat;若 SilentHillPC.exe 正在运行,脚本会直接拦截提示关闭游戏(详见后文错误排查)。

方式二:CMake + Ninja 手动配置构建

在 MSYS2 MinGW x64 终端中执行:

cd silent-hill-decomp/pc_port
cmake -S . -B build -G Ninja -DSH_BUILD_MAP_DLLS=ON
cmake --build build
  • -G Ninja:使用 Ninja 生成器,增量编译速度最快;
  • -DSH_BUILD_MAP_DLLS=ON:关键选项。把 41 张地图编译为运行时动态加载的 DLL(见 pc_port/maps/CMakeLists.txt)。不加它也能编译成功,但游戏只能玩开场区域(只有 map0_s00 被静态编入主程序)。

之后所有增量构建只需:

cmake --build build

常用 CMake 选项速查

选项 默认 说明
SH_BUILD_MAP_DLLS OFF 地图编译为 DLL(桌面平台建议 ON)
SH_STATIC_MAPS OFF 地图静态链接进 exe(互斥于 DLL 模式,iOS 强制使用)
SH_VERSION USA 游戏版本:USA / EUR / JAP0 / JAP1 / JAP2
SH_FMV_FFMPEG ON ffmpeg 影片回退解码(头文件缺失只降级、不阻断构建)
SH_ASAN OFF 开启 AddressSanitizer 内存检测
SH_DEBUG OFF 调试输出

构建成功后的第一次运行

产物位于 pc_port/build/SilentHillPC.exe。构建系统会自动完成三件省心事:

  • 把 pc_port/assets/ 运行时资产复制到 exe 旁边;
  • 把 pc_port/config.cfg 拷入构建目录(已存在则保留你的修改);
  • 生成版本信息头文件,游戏日志会记录具体构建 commit,方便排障。

Silent Hill PC 移植版 PC Launcher 启动器配置界面

运行 SilentHillPC.exe 开始游戏,或运行 SilentHillPC_Launcher.exe 在图形界面中调整分辨率、帧率上限(fps_cap)、渲染后端(renderer = d3d11 / vulkan / warp)等。

常见编译错误与排查方案

# 错误信息 原因 解决方法
1 PsyCross not found. Set PSYCROSS_DIR... 子模块未初始化 仓库根目录执行 git submodule update --init --recursive
2 'cmake' is not recognized 或链接 32 位库 用错了终端 必须使用 MSYS2 MinGW x64 终端,不能用 cmd / PowerShell / 32 位 MSYS shell
3 cannot open output file SilentHillPC.exe: Permission denied 游戏正在运行,链接器无法覆盖 exe 关闭游戏窗口后重新 cmake --build build
4 SDL2 not found 或 SDL2 相关链接错误 未装 SDL2 开发包 pacman -S mingw-w64-x86_64-SDL2 后重新 configure
5 SH_FMV_FFMPEG=ON but ffmpeg 6.0+ development headers were not found 缺 ffmpeg 头文件 pacman -S mingw-w64-x86_64-ffmpeg;不装也能构建,只是 mp4/mkv 影片替换不可用
6 implicit-function-declaration / incompatible-pointer-types 报 error 用了非 MSYS2 的系统 GCC(GCC 14 把警告升级为错误) 确认 PATH 中 gcc.exe 来自 C:\msys64\mingw64\bin;项目已对 MinGW GCC 14 做了降级处理
7 能玩但只有开场地图 漏了 -DSH_BUILD_MAP_DLLS=ON 重新 configure:cmake -S . -B build -G Ninja -DSH_BUILD_MAP_DLLS=ON
8 SH_BUILD_MAP_DLLS and SH_STATIC_MAPS are mutually exclusive. 两个互斥选项同时为 ON 二选一,桌面构建只保留前者

细节说明

关于错误 3(Permission denied):这是 Windows 构建最高频的“吓人但无害”错误。build.bat 在每次构建前都会检查 SilentHillPC.exe 进程,命中即拦截;手动构建时遇到同样报错,任务管理器结束进程即可。

关于错误 5(ffmpeg 降级):CMake 只会打印 WARNING 并跳过该特性,不会中断构建(详见 pc_port/docs/fmv_files.md)。若需指定自定义 ffmpeg 头文件路径,可用 -DSH_FFMPEG_PREFIX=<prefix>。

关于 SH_VERSION:默认编译 USA 版(VER_USA 宏)。日版/欧版光盘玩的话,运行时用启动器选区即可自动识别,一般无需重新编译。

常见问题(FAQ)

Q1:Linux / macOS 能构建吗? 支持但仍在完善中(WIP),官方建议目前优先使用 Windows 或 Wine 运行。

Q2:构建目录能直接删吗? 可以,但 build/gamedata、build/save、build/config.cfg 会被一并删除。用 build.bat nuke 则会自动保留这三项。

Q3:改了源码后需要重新 configure 吗? 不需要。pc_port/src 下的文件使用 CONFIGURE_DEPENDS 通配,直接 cmake --build build 就能拾取新增/修改的源文件。

小结

Silent Hill PC 移植版的构建流程可以浓缩为四步:

  1. 安装 MSYS2 并 pacman -S 六个依赖包;
  2. git clone + git submodule update --init --recursive;
  3. cmake -S . -B build -G Ninja -DSH_BUILD_MAP_DLLS=ON;
  4. cmake --build build(或直接双击 pc_port/build.bat)。

构建成功后把游戏镜像放入 pc_port/build/gamedata/,运行 SilentHillPC.exe 即可从原生编译的《寂静岭》开场一路通关。更多背景可查阅 README.md 与 pc_port/CHANGELOG.md。

登录后查看全文
silent-hill-decomp