- 游戏开发
【免费下载链接】vcmi
Open-source engine for Heroes of Might and Magic III
本篇指南以 VCMI（开源《英雄无敌 III》引擎）官方 macOS 安装文档为主体，系统讲解在 macOS（Intel 与 Apple Silicon）上安装 VCMI 客户端、处理 macOS 15 及以后版本的"未验证开发者"拦截、以及两种导入《英雄无敌 III》正版数据文件的完整流程。读完本文，你将能够独立完成 VCMI 的安装与数据部署，并在遇到常见启动与导入问题时自主排查。
前置知识：为什么需要《英雄无敌 III》数据文件
VCMI 是一个重写《魔法门之英雄无敌 III》（Heroes of Might and Magic III，简称 HoMM3）游戏引擎的开源项目，但它不包含任何游戏美术、音频与地图资源。引擎代码与游戏数据是分离的：你需要自己拥有正版 HoMM3，并将其中的Data、Maps、Mp3三个目录提供给 VCMI 使用。这也是本文第二步的核心任务。
从源码中的校验逻辑看，VCMI 启动器要求的数据属于Shadow of Death（死亡阴影）或 Complete Edition（完整版）：在 launcher/firstLaunch/firstlaunch_moc.cpp 的验证函数中，只有当Data目录下存在以H3ab开头的.lod文件（SoD 的标志性资源包）时才会通过校验；同时会明确拒绝 Heroes III: HD Edition（其特征是存在.pak文件）。因此请确保你手中的是 SoD 或 Complete Edition 版本的数据。
第一步：下载并安装 VCMI
方式一：使用正式发布版（推荐）
正式发布版相对稳定，适合绝大多数玩家，有两种获取途径：
- 手动下载：前往项目 releases 页面下载最新版本（macOS 的发布产物是
.dmg或.app压缩包）； - 通过 Homebrew 安装（两种渠道二选一）：
- 官方 cask：
brew install --cask vcmi - 项目自有 tap：
brew install --cask vcmi/vcmi/vcmi
- 官方 cask：
方式二：使用每日构建版（可能不稳定）
如果你希望抢先体验开发分支（develop）的新功能，可以使用每日构建，需按 CPU 架构选择对应产物：
- Intel（x86_64）构建：适用于 2020 年以前发布的 Mac 机型；
- Apple Silicon（arm64）构建：适用于 M1/M2/M3/M4 系列芯片的 Mac。
注意：每日构建基于开发分支，可能存在未修复的缺陷，建议普通玩家优先使用正式发布版。
处理"无法打开"：绕过 Gatekeeper 拦截
由于 VCMI 并非通过 App Store 分发，macOS 的 Gatekeeper 机制可能会阻止未签名应用首次启动。如果双击应用后没有正常打开，请按以下步骤处理：
- 在 Finder 中右键点击VCMI 应用（App Bundle），选择菜单中的Open（打开）项；
- 在弹出的对话框中点击Open（打开）按钮即可放行。
在macOS 15 Sequoia 及以后版本中，上述对话框不再提供Open按钮，而是显示如下提示：
此时需要进入系统设置解除拦截：
- 打开系统设置（System Settings）；
- 进入隐私与安全性（Privacy & Security）标签页；
- 向下滚动，找到被拦截的应用条目，点击仍要打开（Open Anyway）按钮（下图中箭头所指位置）；
- 在后续确认对话框中确认操作，并输入管理员密码。
第二步：安装《英雄无敌 III》数据文件
数据文件的导入有两条路径：一条是通过 GOG 离线安装包自动导入（推荐，最省事），另一条是经典的"解包已有游戏文件后手动放置"方式。二者任选其一即可。
方式 A：使用 GOG 离线安装包（推荐）
如果你在 GOG 平台购买过 HoMM3 Complete Edition，可以直接从浏览器下载 GOG 的离线安装包（offline installer），然后在 VCMI 启动器中完成导入，全程无需命令行。
具体操作：
- 在 GOG 下载页面获取离线安装包（通常由
setup_xxx.exe与配套的setup_xxx-1.bin等多个分卷文件组成，见下图）； - 打开 VCMI 启动器，进入数据导入界面；
- 先选择
.exe文件； - 启动器会自动定位与之匹配的
.bin文件（前提是选择了正确的安装包，且.exe与.bin位于同一目录）； - 等待导入完成——整个过程可能需要数秒，请耐心等待，不要中途关闭。
底层实现：启动器如何"自动匹配"与校验
这段看似简单的流程背后有完整的工程实现，了解它有助于你判断导入失败的原因：
- 自动匹配
.bin的规则：在 launcher/firstLaunch/firstlaunch_moc.cpp 中，启动器将.bin文件名推导为exeInfo.completeBaseName() + "-1.bin"（即与.exe同名、后缀为-1.bin），若该候选文件存在则直接采用，否则弹窗让用户手动选择； - 文件魔数校验：
.exe文件会被检查是否以MZP开头，.bin文件会被检查是否以idska32开头（见 firstlaunch_moc.cpp 与 firstlaunch_moc.cpp），防止选错文件； - 内嵌 innoextract 解包：VCMI 启动器内置了 innoextract 库（见 launcher/innoextract.h 与 launcher/CMakeLists.txt），在 launcher/innoextract.cpp 中直接调用其 C++ API 解包 GOG 安装器（Inno Setup 格式），无需外部安装；
- SHA1 哈希校验：在 launcher/innoextract.cpp 中内置了一份已知 GOG 安装包的 SHA1 哈希与文件大小表（覆盖英文、法文、波兰文、俄文等多个语言版本，以及 Heroes Chronicles 系列），用于检测文件是否损坏、语言是否匹配，并给出"Unknown files! Maybe files are corrupted?"之类的明确报错；
- 导入前数据校验：解包完成后，启动器会检查临时目录中是否存在包含
.lod文件的data目录，再执行 performCopyFlow 将文件按Data/Maps/Mp3分类复制到用户数据目录（目标路径由VCMIDirs::get().userDataPath()决定）。
方式 B：经典方式（手动解包与放置）
如果你不是 GOG 用户，或者手头只有 Windows 版安装介质，可以使用经典方式：
解包 Windows 版《英雄无敌 III》或 GOG 安装器，可选途径包括：
- 使用 VCMI 应用包内自带的
vcmibuilder脚本（仓库根目录下即有此脚本，见下文详解）； - 在 Mac 上通过CrossOver或Kegworks这类兼容层先安装游戏，再取出游戏目录。
- 使用 VCMI 应用包内自带的
将解包得到的
Data、Maps、Mp3三个目录放置（或符号链接）到用户数据目录：~/Library/Application Support/vcmi/即最终应形成类似
~/Library/Application Support/vcmi/Data、~/Library/Application Support/vcmi/Maps、~/Library/Application Support/vcmi/Mp3的结构。
深入理解vcmibuilder脚本
仓库根目录下的 vcmibuilder 是一个纯 bash 编写的数据构建工具，支持从多种数据来源生成 VCMI 所需文件树。在 macOS 上其默认输出目录正是~/Library/Application Support/vcmi（见 vcmibuilder，脚本会根据uname判断 Darwin 平台）。它的命令行参数如下：
| 参数 | 作用 | 依赖/说明 |
|---|---|---|
--cd1 DIRECTORY | 指定已挂载的第一张 CD（含 Heroes 3 安装文件） | 需要unshield工具 |
--cd2 DIRECTORY | 指定第二张 CD（含 Heroes 3 数据文件） | 会复制Heroes3.vid与Heroes3.snd到Data目录 |
--gog EXECUTABLE | 指定 GOG 离线安装包.exe文件 | 同名.bin分卷必须位于同一目录；需要innoextract（版本需不低于 1.6，见 vcmibuilder）在 PATH 中 |
--data DIRECTORY | 指定已安装好的 Heroes 3 数据目录 | 与 gog/cd 选项互斥，同时指定时 gog/cd 会被忽略 |
--convertMP3 | 将所有 mp3 转为 ogg/vorbis 格式 | 需要ffmpeg或avconv |
--dest DIRECTORY | 指定输出目录 | 默认在 macOS 为~/Library/Application Support/vcmi，在 Linux 为~/.local/share/vcmi |
--validate | 执行基本完整性校验 | 检查Data/H3bitmap.lod、Data/H3sprite.lod、Data/VIDEO.VID是否存在（见 vcmibuilder） |
典型用法示例（GOG 安装包导入并转码音乐、附带校验）：
./vcmibuilder --gog ./setup_heroes_of_might_and_magic_3_complete_4.0_\(28740\).exe --convertMP3 --validate需要注意：脚本在检测到选项组合存在风险（例如同时指定了多个数据源、或选择的选项无法凑齐完整数据）时会打印警告并询问Do you wish to continue? (y/n)，确认后才会继续（见 vcmibuilder）。
用户数据目录与路径说明
无论在启动器中导入还是手动放置，macOS 上的 VCMI 用户数据目录都固定为~/Library/Application Support/vcmi/。该路径由 lib/VCMIDirs.cpp 中的VCMIDirsOSX::userDataPath()硬编码返回（源码注释说明因无法在此处调用 Cocoa API，采用了等效的硬编码实现）；日志则写入~/Library/Logs/vcmi（见 lib/VCMIDirs.cpp）。
如果你希望在不复制大文件的情况下使用已有数据，可以改用符号链接：
ln -s /path/to/your/Heroes3/Data ~/Library/Application Support/vcmi/Data ln -s /path/to/your/Heroes3/Maps ~/Library/Application Support/vcmi/Maps ln -s /path/to/your/Heroes3/Mp3 ~/Library/Application Support/vcmi/Mp3提示：VCMI 官方要求的是 Shadow of Death 或 Complete Edition 数据；直接放置目录前，请确认数据来源符合要求（参考上文提到的启动器校验规则）。
常见问题排查
- 应用打不开：按第一步的 Gatekeeper 放行流程操作；macOS 15 及以后务必走"系统设置 → 隐私与安全性 → 仍要打开"。
.bin没有被自动识别：确认.exe与.bin位于同一文件夹，且选择的是同一个安装包的完整分卷；手动选择.bin文件亦可。- 提示"Unknown files! Maybe files are corrupted?"：说明所选安装包与启动器内置哈希表不匹配或文件不完整，请从 GOG 重新下载完整分卷。
- 提示"Failed to detect valid Heroes III data"：所选目录不是 SoD/Complete 版数据，或混入了 HD Edition（
.pak）文件，请更换数据来源。 - 导入后没有音乐：可检查是否遗漏
Mp3目录；Mp3目录在部分场景下为可选资源。
关联阅读
- 想要在 macOS 上从源码自行编译 VCMI，请参阅 Building VCMI for macOS，其中明确说明"编译产物运行前同样需要按本文档安装游戏文件"；
- 其他平台的安装指南：Linux、Windows、iOS、Android；
- 若遇到游戏内问题需要反馈，可参考 Bug Reporting Guidelines 的流程提交报告。
- 游戏开发
【免费下载链接】vcmi
Open-source engine for Heroes of Might and Magic III
相关推荐
VCMI Android 端安装全指南：从 APK 安装到导入《英雄无敌 III》数据文件
VCMI Android 端安装全指南：从 APK 安装到导入《英雄无敌 III》数据文件 本篇指南完整讲解如何在 Android 设备上安装 VCMI（《魔法
游戏开发VCMI 在 Windows 上的完整安装指南：从下载安装到 Heroes III 数据导入与目录定制
VCMI 在 Windows 上的完整安装指南：从下载安装到 Heroes III 数据导入与目录定制 导读 本指南面向在 Windows 平台上安装 VCMI
游戏开发VCMI 玩家指南：安装并游玩 Heroes Chronicles（英雄无敌历代记）
VCMI 玩家指南：安装并游玩 Heroes Chronicles（英雄无敌历代记） VCMI 作为《英雄无敌 III》的开源引擎，不仅支持原版战役，也完整支持
游戏开发
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
