Porymap从源码编译实战:Windows、macOS、Linux三大平台Qt环境搭建避坑指南
Porymap从源码编译实战:Windows、macOS、Linux三大平台Qt环境搭建避坑指南
Porymap 是一款面向 Pokémon 第三世代反编译项目(pokeemerald、pokefirered、pokeruby)的开源地图编辑器。对 Linux 用户而言,官方不提供预编译包,必须自己从源码编译;而在 Windows 与 macOS 上,编译源码能让你用上尚未发布的最新功能,或为自定义项目做二次开发。本文带你完成 Porymap 源码编译:先讲清 Qt 版本、C++17 与依赖模块这些最容易踩的坑,再给出 Windows、macOS、Linux 三大平台从零到跑通的完整步骤,最后汇总一份高频报错避坑清单。
上图就是编译成功、运行 Porymap 并加载项目后的主界面:左侧是地图分组列表,中间是地图 / 事件 / 连接编辑区,右侧是 Metatiles(元图块)面板。
一、编译前必知:Qt 版本、C++17 与依赖清单
很多报错都源于"环境没配齐"。动手之前,先对照这张清单确认你的 Qt 环境:
| 项目 | 要求 | 说明 |
|---|---|---|
| Qt 版本 | ≥ 5.14.2,兼容 Qt 6(6.8 / 6.10) | 官方 CI 同时测试 5.14.2 与 6.8.* |
| C++ 标准 | C++17 | 见 porymap.pro 中的 -std=c++17 |
| 必装 Qt 模块 | core、gui、widgets | 基础构建必需 |
| 推荐 Qt 模块 | charts、qml、network | 缺失会打印警告并禁用对应功能(如宝可梦分布图表) |
| 构建工具 | qmake + make |
Windows 上为 qmake + nmake / mingw32-make |
| 第三方库 | QtGifImage(已内置) | 随源码打包于 src/vendor/QtGifImage/,无需单独安装 |
💡 两个小坑提前说:
- C++17,而不是 C++11:早期 INSTALL.md 标注为 C++11,但构建文件实际用
-std=c++17。现代 GCC / Clang / MSVC 默认即支持,老编译器才需要升级。 - Charts 模块决定"图表"是否可用:项目通过
qtHaveModule(charts)探测 porymap.pro,若缺失会提示Qt module 'charts' not found, disabling chart features.,程序能编译但 Wild Pokémon 图表不可用。想要完整体验,务必装上qtcharts。
二、通用编译三步走:qmake → make → 运行
三大平台的主流程完全一致,记住这三步即可,后面的差异只在"装 Qt"和"启动方式"上:
# 1. 获取源码
git clone https://gitcode.com/gh_mirrors/po/porymap
cd porymap
# 2. 配置 + 编译(-j 并行加速)
qmake
make -j$(nproc) # Windows 上换成 nmake 或 mingw32-make
# 3. 运行产物(路径见第七节)
qmake 会读取根目录的 porymap.pro 生成 Makefile,make 再据此编译链接。入口点是 src/main.cpp,编译后会生成名为 porymap 的可执行程序或 porymap.app 应用包。
三、Windows 平台编译 Porymap
Windows 上最省心的是 Qt Creator + 合适的构建套件(Kit):
- 安装 Qt:使用官方 Qt 安装器,勾选
Qt 6(或 5.14.2)及一个编译器套件(MinGW 或 MSVC)。安装模块时记得勾选Charts、QML、Network,避免后面缺库。 - 打开工程:在 Qt Creator 中"打开文件"选择仓库根目录的 porymap.pro,选择目标 Kit,构建类型选 Release。
- 编译:点击"构建项目"即可;产物通常位于
release\porymap.exe或build-porymap-<Kit>-Release\porymap.exe。
如果你更喜欢命令行(MinGW 套件):
# 确认 qmake 与 make 都在 PATH
qmake --version
# 配置并编译(MinGW 用 mingw32-make;MSVC 用 nmake)
qmake porymap.pro
mingw32-make -j8
⚠️ Windows 专属提醒:仓库的自动化静态构建任务目前在 CI 中处于禁用状态,因此最稳妥的路径是 Qt Creator + 完整模块的 Kit。若报"找不到 charts / qml 模块",多半是安装器里没勾选对应模块,重装或补装后再重新
qmake。
四、macOS 平台编译 Porymap
macOS 官方推荐使用 Homebrew 装 Qt(参考 INSTALL.md):
# 1. 安装命令行工具与 Qt
xcode-select --install
brew update && brew upgrade
brew install qt # 该元包已包含 Charts / QML / Network
# 2. 克隆并进入源码
git clone https://gitcode.com/gh_mirrors/po/porymap
cd porymap
# 3. 配置(-config release 避免 Debug 依赖)+ 编译
qmake -config release porymap.pro
make -j8
macOS 的产物是应用包 porymap.app,而不是单个可执行文件,所以启动方式是:
./porymap.app/Contents/MacOS/porymap
📦 需要分发给别人? 直接拷贝
porymap.app会缺少 Qt 动态库。用macdeployqt把依赖打进包里,并顺带生成.dmg:macdeployqt porymap.app -dmg这也是 CI 的 macOS 打包步骤 所用的命令。
五、Linux 平台编译 Porymap(Ubuntu / Arch)
Linux 必须源码编译。关键是装对 Qt 基础 + Charts 模块,并注意 qmake 指向的是 Qt6。
Ubuntu / Debian(参考 INSTALL.md):
# Qt6(推荐);若发行版版本较旧,退回 Qt5 的 qtdeclarative5-dev
sudo apt-get install qt6-base-dev qt6-declarative-dev qt6-charts
git clone https://gitcode.com/gh_mirrors/po/porymap
cd porymap
qmake
make -j$(nproc)
./porymap
Arch Linux(参考 INSTALL.md):
sudo pacman -S qt6-base qt6-declarative qt6-charts
git clone https://gitcode.com/gh_mirrors/po/porymap
cd porymap
qmake
make -j$(nproc)
./porymap
💡 系统里若同时存在 Qt5 与 Qt6,先用
qmake --version核对版本;需要 Qt6 时改用qmake6,或调整PATH让 Qt6 的bin排在前面。
六、高频报错与避坑清单
编译并运行后,Porymap 的全部功能窗体都可以正常使用,例如下图的快捷键编辑器:
遇到报错别慌,下面这张表覆盖了绝大多数情况:
| 现象 / 报错 | 原因 | 解决办法 |
|---|---|---|
Qt module 'charts' not found 警告 |
未安装 Charts 模块 | Arch: qt6-charts;Ubuntu: qt6-charts;Qt 安装器补勾 Charts |
C++ 语法 / #error 报错 |
编译器过旧,不支持 C++17 | 升级 GCC / Clang,或改用 MSVC 2019+ |
qmake 版本与 Qt 不一致 |
多版本共存,PATH 指向错误 | qmake --version 核对,改用 qmake6 或调整 PATH |
| Windows 找不到 charts / qml 模块 | 安装器未勾选模块 | 重装或补装对应模块,重新 qmake |
mingw32-make: not found |
MinGW 未进 PATH | 把 MinGW 的 bin 加入 PATH,MSVC 用户改用 nmake |
macOS ./porymap 无此文件 |
产物是 .app 包 |
运行 ./porymap.app/Contents/MacOS/porymap |
| 编译很慢 | 未开并行 | make -j$(nproc)(Windows:-j8) |
七、编译产物在哪?如何启动
| 平台 | 产物位置 | 启动命令 |
|---|---|---|
| Linux | 当前目录 ./porymap |
./porymap |
| macOS | 当前目录 ./porymap.app |
./porymap.app/Contents/MacOS/porymap |
| Windows | release\ 或 build-porymap-*\ |
双击 porymap.exe |
程序首次运行时会读取项目配置文件(如 porymap.project.cfg),加载一个 pokeemerald / pokeruby / pokefirered 工程后即可开始画地图。下图是新建地图时的选项窗,能正常弹出并填写,就说明你这一路的 Qt 环境、C++17 与依赖模块全部到位了:
八、小结
- 环境三要素:Qt ≥ 5.14.2(兼容 Qt6)、C++17、
core/gui/widgets必装,charts推荐装。 - 主流程统一:
git clone→qmake→make -j→ 运行,差异只在"装 Qt"与"启动方式"。 - 产物形态:Linux 是
./porymap,macOS 是porymap.app应用包,Windows 是porymap.exe。 - 第三方库免安装:QtGifImage 已随源码打包,克隆即可编译。
照着本文走完三大平台任意一条路径,你就能拥有一个最新、且可二次定制的 Porymap 地图编辑器。更多构建细节可参考工程根目录的 porymap.pro、INSTALL.md 与变更记录 CHANGELOG.md。


