Porymap从源码编译实战:Windows、macOS、Linux三大平台Qt环境搭建避坑指南

原创2026-11-03 20:03:221,821 阅读
文章标签:游戏开发开发工具桌面应用

Porymap从源码编译实战:Windows、macOS、Linux三大平台Qt环境搭建避坑指南

Porymap 是一款面向 Pokémon 第三世代反编译项目(pokeemerald、pokefirered、pokeruby)的开源地图编辑器。对 Linux 用户而言,官方不提供预编译包,必须自己从源码编译;而在 Windows 与 macOS 上,编译源码能让你用上尚未发布的最新功能,或为自定义项目做二次开发。本文带你完成 Porymap 源码编译:先讲清 Qt 版本、C++17 与依赖模块这些最容易踩的坑,再给出 Windows、macOS、Linux 三大平台从零到跑通的完整步骤,最后汇总一份高频报错避坑清单。

Porymap 地图编辑器编译成功后加载项目的主窗口界面

上图就是编译成功、运行 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):

  1. 安装 Qt:使用官方 Qt 安装器,勾选 Qt 6(或 5.14.2)及一个编译器套件(MinGW 或 MSVC)。安装模块时记得勾选 Charts、QML、Network,避免后面缺库。
  2. 打开工程:在 Qt Creator 中"打开文件"选择仓库根目录的 porymap.pro,选择目标 Kit,构建类型选 Release。
  3. 编译:点击"构建项目"即可;产物通常位于 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 的全部功能窗体都可以正常使用,例如下图的快捷键编辑器:

Porymap 编译成功后可正常使用的 Shortcuts Editor 快捷键编辑器

遇到报错别慌,下面这张表覆盖了绝大多数情况:

现象 / 报错 原因 解决办法
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 与依赖模块全部到位了:

Porymap 编译成功后打开的新建地图选项窗口,用于验证构建是否成功

八、小结

  • 环境三要素: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。

登录后查看全文
porymap