Axmol 开发环境快速搭建指南

halx99
97 阅读4分钟

🚀 快速开始

1. 安装 PowerShell 7

  • Windows

    • Windows 10+ 默认包含 PowerShell 5.x，可正常使用。
      👉 推荐安装 PowerShell 7。
    • 执行策略（Windows 必需）
      • 如果是克隆的 Axmol 仓库： 
        Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force
      • 如果是下载的 ZIP 发行版（建议在下载后验证 MD5 或 SHA256 摘要）： 
        Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Bypass -Force
      ⚠️ 注意：RemoteSigned 比 Bypass 更安全。

  • macOS / Linux

    • 直接运行 setup.ps1。（提示：setup.ps1 在 macOS/Linux 上也可以用 bash 模式 执行。）

2. 安装编译工具链

  • Windows: 安装 Visual Studio 2022 或 2026，并勾选 Desktop development with C++ 工作负载。

    • 如果需要 UWP 开发，还需启用 WinUI application development tools 工作负载，并勾选可选组件 C++ Universal Windows Platform tools。

  • macOS:

    • 对于 axmol-v2：安装 Xcode 14.2 或更高版本 —— 注意，Xcode 14.2 仅支持在 macOS 12.5 ~ macOS 13.x 上运行。
    • 对于 axmol-v3：安装 Xcode 16.4 或更高版本，其要求 macOS 15.3 或更新版本。

  • Linux: 确保已安装 GCC/G++（Ubuntu 22.04+、Debian 12+、ArchLinux）。

3. 运行安装脚本

./setup.ps1

该脚本会安装依赖并配置环境变量。完成后请重启终端。在 Linux 上可能需要重新登录当前系统用户，按照提示操作即可。

4. 创建新项目

axmol new -p dev.axmol.hellocpp -d ./projects -l cpp HelloCpp
  • -l 可以是 cpp 或 lua
  • --portrait 可选，生成竖屏项目

5. 构建项目

axmol

默认会构建你开发机上的宿主目标。
使用 -p 参数可以交叉编译到其他平台。

📦 常用构建命令

平台示例命令
Windowsaxmol -p win32
UWPaxmol -p winuwp
Linuxaxmol -p linux
macOS x64axmol -p osx -a x64
macOS arm64axmol -p osx -a arm64
iOS (模拟器)axmol -p ios -a x64 -sdk sim
iOS (真机)axmol -p ios -a arm64 -c
tvOS (模拟器)axmol -p tvos -a arm64 -sdk sim
tvOS (真机)axmol -p tvos -a arm64 -c
Android APKaxmol -p android -a arm64
Android AABaxmol -p android -a arm64 -aab
WASMaxmol -p wasm
WASM64(需要 v3)axmol -p wasm64

🔑 常用参数

  • -p <platform>
    指定目标平台，例如 win32、linux、osx、ios、android、wasm 等。

  • -a <arch>
    指定目标架构，例如 x64、arm64。在 macOS、iOS、tvOS、Android 等多架构平台上尤其重要。

  • -c
    生成 IDE 工程文件（如 Visual Studio .sln 或 Xcode .xcodeproj）。在 iOS/tvOS 真机构建时必须使用，因为需要代码签名。

  • -sdk <name>
    指定 SDK 类型，例如 sim 表示模拟器构建。

  • -aab
    在 Android 平台生成 AAB 包（Google Play 要求），默认生成 APK。

  • -O<n>
    指定构建优化等级：

    • -O0 → Debug
    • -O1 → MinSizeRel
    • -O2 → RelWithDebInfo（默认）
    • -O3 → Release

👉 注意事项:

  • 你可能注意到在 iOS (真机) 和 tvOS (真机) 的命令中我们加了 -c 参数。这是因为真机构建必须进行代码签名。目前需要打开生成的 Xcode 工程手动配置签名。
  • axmol 命令是 axmol build 的简写，使用 axmol build -h 可以查看所有可用选项和详细说明。
  • Wasm: 在所有开发操作系统（macOS、Windows、Linux）上均受支持。请确保已安装 Python 3.13 或更高版本。
    👉 在 PowerShell 终端中运行 python -V 以确认当前 Python 版本，之后使用 axmol run -p wasm 即可构建并直接启动浏览器运行你的游戏项目。

🛠️ IDE 集成

Axmol CLI 覆盖了大多数平台的构建需求。

  • 对于 Windows / Linux / macOS (模拟器)，IDE 是可选的。

  • 对于 iOS/tvOS 真机，IDE 是必须的，因为需要在 Xcode 中进行代码签名。

  • Visual Studio (Windows)
    运行 axmol -c，然后打开生成的解决方案文件：

    • VS2022 → build/ProjectName.sln
    • VS2026 → build/ProjectName.slnx

  • Xcode (macOS/iOS/tvOS)
    运行 axmol -p osx/ios/tvos -c，然后打开生成的 .xcodeproj

    ⚠️ 对于 iOS/tvOS 真机构建，必须在 Xcode 中打开工程并手动配置签名。

  • Android Studio
    运行 axmol -p android -c，然后打开 proj.android

📦 构建签名的发布版本 (APK / AAB)

适用于 CI/CD 工作流：

axmol -p android -a arm64 -xc "-PKEY_STORE_FILE=/path/to/your-app.jks,-PKEY_STORE_PASSWORD=<your_key_store_passwd>,-PKEY_ALIAS=<your_key_alias>,-PKEY_PASSWORD=<your_key_passwd>"

如果需要生成带签名的 AAB 包 ，只需要添加参数 -aab 即可。

⚙️ 高级配置 / 常见问题

  • Windows Build Tools: Axmol 支持仅安装 BuildTools，而不安装完整的 Visual Studio IDE。
    但我们强烈推荐安装 Visual Studio 2022 或 2026 IDE，这会为你的 Windows 平台开发带来最佳体验 —— 在我们看来，它是地球上最强大的 IDE。
  • Windows clang: 在 Windows 平台，我们还支持使用 clang 构建 Win32 目标平台，命令: axmol -cc clang 即可。
  • Linux: 使用 VSCode 并安装 C++ 和 CMake Tools 扩展，以获得最佳开发体验。
    👉 请确保系统已安装 GCC/G++ 和 CMake（推荐使用 Ubuntu 22.04+、Debian 12+ 或 ArchLinux）。
  • Android SDK/NDK: setup.ps1 -p android 会安装最低版本的 NDK — axmol-v2 使用 r23d，axmol-v3 使用 r27d。
  • WASM 调试: 默认 emsdk 版本是 3.1.73。调试可使用 Chrome DevTools。

🎯 总结

最简流程只有三步：

  1. ./setup.ps1
  2. axmol new
  3. axmol build

其他步骤都是可选或高级用法。

📚 更多帮助

更多常见构建问题请查看：
Axmol FAQ – 构建

avatar
文章
阅读
粉丝