如何从源码构建 Silent Hill PC 移植版:CMake+Ninja+MSYS2 完整编译教程与常见错误排查
如何从源码构建 Silent Hill PC 移植版:CMake+Ninja+MSYS2 完整编译教程与常见错误排查
本文教你用 CMake + Ninja + MSYS2(MinGW-w64)从零构建 Silent Hill PC 移植版(silent-hill-decomp):一个基于 PSX 反编译的《寂静岭1》原生 PC 移植项目。它不是模拟器,而是直接用反编译出的 C 源码编译出真实的 Windows 可执行文件,支持任意分辨率、宽屏、高刷新率与 Mod。下面给出完整的从源码构建步骤,并逐一排查最常见的编译错误。
构建前先了解项目结构
整个仓库由两部分组成,理解它们能帮你读懂绝大多数报错:
| 目录 | 作用 |
|---|---|
| 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 生成器)。
- 安装 MSYS2,然后打开 “MSYS2 MinGW x64” 终端(注意:不要用 32 位的 MSYS shell);
- 一键安装工具链与依赖库:
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 影片替换
- 克隆仓库并初始化 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
- 准备游戏光盘镜像(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,方便排障。
运行 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 移植版的构建流程可以浓缩为四步:
- 安装 MSYS2 并
pacman -S六个依赖包; git clone+git submodule update --init --recursive;cmake -S . -B build -G Ninja -DSH_BUILD_MAP_DLLS=ON;cmake --build build(或直接双击 pc_port/build.bat)。
构建成功后把游戏镜像放入 pc_port/build/gamedata/,运行 SilentHillPC.exe 即可从原生编译的《寂静岭》开场一路通关。更多背景可查阅 README.md 与 pc_port/CHANGELOG.md。

