Cocos2d-x 3.17.2 环境搭建与 Android 构建边界｜默然的博客

本文记录的是 Cocos2d-x 3.17.2 旧项目维护环境，不是新项目的通用安装指南。该版本的 Android 模板、NDK、Gradle 与 Android Studio 必须按项目实际构建脚本配套；不要把不同年代的工具版本直接拼在一起。

准备下载

必须

• Cocos2d-x 3.17.2 源码标签
• Python 2.7.18（已停止维护），仅在旧版 cocos2d-console 确实依赖时使用

Win32 平台

Android 平台

• Android SDK 与 Android Studio：以项目 Gradle Wrapper 支持范围为准。
• Android NDK：Cocos2d-x 3.17 的发布说明使用 NDK r16；原项目若锁定 r13b，应保留原有工具链并在独立环境中维护。
• JDK：版本由 Gradle／Android Gradle Plugin 决定，不能只根据系统已安装的 JDK 选择。

创建 Cocos2d-x 工程

在 cocos2d-x-3.17.2\tools\cocos2d-console\bin\ 路径下执行。原文的 3.9 路径与本文目标版本不一致：

cocos new projectName -p packageName -l language -d projectPath

Win32 构建

按工程随附的解决方案、第三方库与编译器工具集配置。不要将 Android 章节的 NDK、Gradle 设置套用到 Win32。

Android 构建

环境变量与本地路径

1. 安装项目所需的 Android SDK、NDK、JDK 和 CMake；版本以仓库中的 Gradle、Application.mk、build.gradle 及历史构建记录为准。
2. 如构建脚本需要，可配置 ANDROID_SDK_ROOT、NDK_ROOT 与 JAVA_HOME。不要再手工设置 CLASSPATH 中的 dt.jar、tools.jar；它们是旧 JDK 布局的做法。
3. local.properties 只保存机器本地路径，不应提交到仓库。旧版模板常见写法如下，键名是 ndk.dir，不是 ndk.Path：

sdk.dir=D\:\\software\\AndroidSDK
ndk.dir=D\:\\software\\android-ndk-r13b

命令行构建

cocos compile -p android -l lua -m debug

Android Studio

用 Android Studio 打开项目的 Android 工程即可。不要直接把 Gradle 7.1.1 和 Android Gradle Plugin 7.4 写进旧模板：它们与 r13b 等旧 NDK 工具链通常不兼容。升级前应单独评估 Gradle、AGP、JDK、NDK、CMake 和原生插件的完整组合。

常见问题

找不到 JDK、NDK 或 SDK

先核对当前终端／IDE 实际读取到的路径、local.properties 与项目声明的版本。修改系统环境变量后，通常需要重启 IDE 或新开终端；仅重启并不能修复版本不匹配。

打包后黑屏

先检查 APK／AAB 中是否包含资源和 Lua 代码，再检查启动日志、ABI、动态库和首帧异常。若确认是 libcocos2dx 模块遗漏资源，可在对应模块的 build.gradle 配置资源目录；路径必须以当前工程结构为准：

sourceSets.main {
        aidl.srcDir "../java/src"
        java.srcDir "../java/src"
        manifest.srcFile "AndroidManifest.xml"

        assets.srcDir "../../../../../../res/"
        assets.srcDir "../../../../../../src/"
}

不要把示例中的 res、src 相对路径原样复制到其他项目；先以 build.gradle 所在目录计算真实相对路径。

版本结论

Cocos2d-x 官方已不建议新项目从该引擎开始；维护既有 3.17.2 项目时，应锁定一套可复现的旧工具链，而不是盲目升级单个组件。

相关阅读

• Cocos2d-x 获取 Android 与 iOS 设备电池信息
• Cocos2d-x 实现 Android 与 iOS 背景透明