Axmol 开发环境快速搭建指南 (新）

🚀 快速开始

1. 安装 PowerShell 7

• Windows

  • Windows 10+ 默认包含 PowerShell 5.x，可以使用，但推荐安装 PowerShell 7。

  • 执行策略（Windows 必须设置）

    # 如果你是通过 git clone 克隆 Axmol 仓库：
    Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force
    
    # 如果你是下载 ZIP 版本：
    Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Bypass -Force

• 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

该脚本会安装依赖并配置环境变量。完成后请重启终端。

4. 创建新项目

axmol new -p dev.axmol.hellocpp -d ./projects -l cpp HelloCpp

• -l 可以是 cpp 或 lua
• --portrait 可选，生成竖屏项目

5. 构建项目

axmol

默认会构建你开发机上的宿主目标。

使用 -p 参数可以交叉编译到其他平台。

---

📦 常用构建命令

平台	示例命令
Windows	axmol -p win32
UWP	axmol -p winuwp
Linux	axmol -p linux
macOS x64	axmol -p osx -a x64
macOS arm64	axmol -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 APK	axmol -p android -a arm64
Android AAB	axmol -p android -a arm64 -aab
WASM	axmol -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 表示模拟器构建。在 Linux 上可能需要重新登陆当前系统用户，按照提示操作即可。

• -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 构建 Win32 目标平台，命令: axmol -cc clang 即可。
• 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 -- 构建