做独立游戏这几年我用 Android Studio 打包 RPG Maker MV 的 apk次数多得记不清了。每次有朋友问我“官方不是有 Deploy 一键生成吗你为什么非要折腾 Android Studio”我都想拉他坐下来把打包前后那点事从头讲一遍。先说结论RPG Maker MV 官方工具确实能出包但它的最大问题是“你只能得到一个包”而不是“你能掌控这个包”。当你需要自定义包名、更换图标、调整权限、打上自己的签名或者往里面塞一点原生代码时官方一键打包基本帮不上忙。而用 Android Studio 手动打包从工程结构到最终 APK每个环节都是自己说了算。这篇内容适合三种人第一次尝试把 MV 游戏装进手机的独立开发者、想要给 MV 游戏加自定义功能的进阶用户以及被官方打包体积和包名问题折磨过的人。我会把从准备工具到生成 APK 的完整路径拆开讲附带这几年踩过的坑。1. 为什么不用官方一键打包而是折腾 Android Studio1.1 官方打包的痛点MV 官方菜单里有一个“部署”功能可以直接生成安卓 APK看似很方便。但用过的朋友应该都有体会第一生成出来的 APK 体积偏大因为里面塞了很多通用引擎文件第二包名默认是 com.rpgmakermv.xxxx 这种形式上架、更新、统计 SDK 接入时都很别扭第三图标、启动画面、屏幕方向这些参数只能填几个预设值想精细控制相当麻烦。更关键的是官方工具生成的工程是一个黑盒。你没办法在里面对 WebView 做额外的原生处理也没法利用 Android 端的调试工具去排查白屏、加载缓慢这类问题。等游戏做大了你会发现这种“闭门造车”式的打包方式根本撑不住需求。相比之下用 Android Studio 打开的是一个标准 Android 工程主 Activity、WebView 配置、Manifest、Gradle 脚本全都摊在你面前想改哪里改哪里。1.2 手动打包真正的优势手动打包并不是为了炫技而是为了拿到三样东西可控性、可调试性、可持续交付。可控性体现在签名和包名上。你自己生成 keystore自己决定 applicationId后续每次更新都用同一个签名用户安装升级包时不会出现“签名不一致无法覆盖安装”的问题。官方一键打包虽然也能签名但整个流程不够透明出问题很难排查。可调试性更重要。MV 游戏本质上是跑在 WebView 里的网页游戏用 Android Studio 打包后你可以通过 Chrome 的远程调试工具直接查看游戏页面的控制台报错、网络请求和渲染状态。这个能力在官方一键打包里几乎用不上但在手动打包里几乎是白送的——这会让你在处理白屏、脚本报错、资源加载失败时省下大量时间。可持续交付解决的是后续更新问题。手动打包意味着你有一个稳定的工程模板下次游戏更新时只需要替换 www 资源目录、改一下版本号、重新签名打包整个流程异常顺畅不必每次都重新点一遍官方工具。2. 开工前的工具准备JDK、Android Studio 与常见坑2.1 版本匹配是我踩过最大的坑很多人在第一步就卡住了不是不会装软件而是装完之后工程同步报错。最典型的就是 “Unsupported class file major version 61” 这类错误看到它基本可以判断是 JDK 版本和 Gradle 版本不匹配。我的建议是直接使用 Android Studio 自带的 JBRJetBrains Runtime不要在系统里单独装一个 Oracle JDK 然后在项目里乱改路径。Android Studio 在安装时会自带与当前版本匹配的 JBR你只需要在 “Project Structure → SDK Location” 里确认 Gradle 的 JDK 指向它就行。这样能规避掉大半版本兼容性问题。如果你非要自己装 JDK那就记住一个相对稳妥的组合JDK 17 配 Gradle 8.0 以上、Android Gradle Plugin 8.0 以上。老版本 JDK 8 配新版本 AGP 会直接报错新版本 JDK 21 配旧版本 Gradle 也会踩坑所以别跟版本较劲用 IDE 默认的就好。2.2 SDK 平台与构建工具的安装打开 Android Studio 的 SDK Manager建议至少安装两样东西一个较新版本的 Android SDK Platform比如 API 34以及对应版本的 SDK Build-Tools。很多朋友问“Android Studio SDK 无法勾选怎么办”原因一般是下载源不稳定导致列表加载不全。这种情况可以先把 SDK 列表刷新几次或者检查一下本机网络环境如果一直失败可以改用国内镜像源在 SDK Manager 的 “SDK Update Sites” 里手动添加一个可访问的镜像地址这样下载 Platform-Tools 和 Build-Tools 会顺畅很多。这里还要提一个细节构建工具版本不是越高越好要和工程里 compileSdkVersion 的数值配套。比如 targetSdkVersion 用的 33那 Build-Tools 用 33.0.0 或 34.0.0 都行如果 build 过程中出现和 tag number 相关的报错往往就是构建工具版本不匹配导致的这个我后面会专门讲。2.3 第一次启动别慌环境变量与路径Android Studio 安装完成后第一次新建或导入工程会有比较长的下载过程因为它要拉取 Gradle 和依赖库。如果你只是在命令行里用 cordova 生成工程不在 Android Studio 里编译那环境变量只需要配一个JAVA_HOME或者直接用 IDE 内置 JDK如果要在命令行里跑 Gradle 打包那ANDROID_HOME环境变量也得配上指向 SDK 的安装目录。我个人经验是宁可把环境变量配好也不要用 IDE 里的图形界面猜ANDROID_HOME指向/Users/你的用户名/Library/Android/sdkMac或C:\Users\你的用户名\AppData\Local\Android\SdkWindows然后在PATH里加上%ANDROID_HOME%\platform-tools和%ANDROID_HOME%\tools。这样后续使用adb、aapt这类命令行工具会方便很多。3. 把 MV 项目变成 Android 工程核心实操3.1 拿到游戏的 www 目录MV 游戏的所有核心资源都集中在项目根目录下的www文件夹里index.html、js、img、audio、data、fonts全都装在这里。这个目录本质上就是浏览器版本里加载的全部内容是后续打进 APK 的关键。当你用 MV 编辑器打开项目在“部署”选项里选择“Android / iOS”编辑器会生成一个包含 www 的部署目录。但你完全可以不用这个功能直接打开游戏项目的根目录把www整个复制出来。唯一需要注意的是部署目录里的 www 会带上平台相关的配置如果你已经做了移动端适配直接用原始 www 即可如果还没适配建议先在 PC 浏览器里把移动端 UI 和字体大小调好再复制 www。小技巧复制 www 时把save目录一起带上不过要注意安卓端 WebView 的存档路径可能和电脑端不同最好在测试机上多验证几次存档和读档别等玩家报告丢存档才排查。3.2 用 Cordova 创建最省事的壳MV 游戏在安卓上跑起来需要一个壳——本质上就是一套 Android 原生工程里面内置一个 WebView 来加载本地 index.html。目前最省事的方式是用 Cordova 生成这个壳。先确保本机装好了 Node.js然后全局安装 Cordovanpm install -g cordova接着创建一个空白工程cordova create mvstage com.example.mygame MyGame cd mvstage cordova platform add android这里解释一下刚才那条命令中的三段参数mvstage是文件夹名com.example.mygame是你想要的包名MyGame是显示在桌面的应用名。包名最好提前想好后面虽然在 Android Studio 里也能改但不如一开始就定准。cordova platform add android执行后会在platforms/android目录下生成一个完整的 Android Studio 工程。这个工程就是我们要操作的对象。如果你不想用命令行打包到这里就可以关掉终端、打开 Android Studio 了。3.3 替换 www 并配置 config.xmlCordova 生成的工程里默认的网页资源位于platforms/android/app/src/main/assets/www。我们直接把这个目录里的内容删掉把之前准备好的 MV 项目www整个复制进去。这一步最怕文件缺失因为 MV 的资源文件特别多复制时如果因为路径过长或文件名特殊字符导致漏文件游戏运行起来就会黑屏。我的习惯是复制完成后再对一遍文件和大小确保总数一致。接下来改config.xml这个文件在工程根目录下是 Cordova 的全局配置。重点设置这几个项preference nameOrientation valueportrait / preference nameFullscreen valuetrue / preference nameBackgroundColor value0xff000000 / preference nameandroid-minSdkVersion value21 / preference nameandroid-targetSdkVersion value33 /如果你是横屏游戏把Orientation改成landscape或者删掉这一行让它支持自由旋转。Fullscreen设为true会隐藏系统状态栏沉浸感更强BackgroundColor是游戏加载时的背景色设成黑色能避免加载期间出现白屏闪烁。还有一个容易被忽略的配置allow-navigation。如果你的游戏内嵌了远程网页链接或者需要加载在线资源得在这里声明允许跳转的域名纯本地游戏这一项可以不配。4. 在 Android Studio 里完成打包4.1 打开工程并认识关键界面用 Android Studio 打开platforms/android目录点开之后等待 Gradle 同步。第一次同步时间通常比较长因为它要下载项目声明的依赖。如果同步卡在 Gradle 下载那一环我建议去改gradle/wrapper/gradle-wrapper.properties里的distributionUrl把下载地址换成速度更快的国内镜像源指向对应版本号的文件即可。同步成功后你会看到左侧项目结构里有一个app模块和一个cordovaLib模块。app就是你的应用主模块所有业务相关的改动都集中在这里cordovaLib是 Cordova 提供的运行库一般情况下不需要动它。在app模块下重点关注两个地方src/main/AndroidManifest.xml和build.gradle。前者声明应用的包名、权限和入口 Activity后者控制编译版本、依赖和签名配置。MV 游戏要联网就检查INTERNET权限要本地读写就检查WRITE_EXTERNAL_STORAGE不过高版本安卓对存储权限管得严最好在运行时动态申请或者直接让游戏只使用 WebView 的本地存储。4.2 包名、图标与版本号调整如果你在cordova create时已经写清楚包名那么 AndroidManifest 里的package属性和build.gradle里的applicationId应该是一致的。没写清楚也没关系现在手动改也来得及以build.gradle里applicationId为准AndroidManifest 里不要设package冲突值。版本号在build.gradle里处理versionCode 1 versionName 1.0.0versionCode必须是数字每次更新递增商店和系统靠它判断版本新旧versionName是展示给用户看的字符串想写什么写什么。很多人把这两个搞混结果发了三次包用户永远提示“已是最新版本”其实就是 versionCode 没变。图标和启动屏一般放在app/src/main/res目录下按mipmap-mdpi、mipmap-hdpi、mipmap-xhdpi、mipmap-xxhdpi、mipmap-xxxhdpi分目录放不同分辨率的图片。没有特殊要求的话一套 512×512 的图标缩放到各目录即可有启动屏需求的在res/drawable或splash目录里放好图片并在config.xml里声明SplashScreen相关偏好。注意安卓 12 及更高版本强制使用系统自带的应用图标样式过于复杂的圆形图标可能会被系统裁切设计时给图标周围留点安全边距。4.3 生成签名 APK 的方法打开 Android Studio 菜单栏的Build → Generate Signed Bundle or APK选择APK。如果还没有 keystore就点击Create new...新建一个填写好别名、密码、证书有效期这些信息。这里有个最容易让人后悔的细节keystore 文件一旦丢失或密码遗忘你以后永远无法用同一个签名发布更新包。到时候用户只能先卸载旧版再装新版存档全部丢失那场面相当难堪。所以生成 keystore 后加密备份到网盘和本地至少两个地方密码也单独记录。签名配置完成后选择release构建版本点击 Finish。等到底部 Gradle 任务跑完APK 会输出到app/build/outputs/apk/release/目录下。这个 APK 是带签名的正式包可以发给测试人员安装也可以直接上传应用市场。构建过程中如果遇到需要额外配置的签名信息也可以在build.gradle里的android块下添加signingConfigs节点不过图形界面操作已经覆盖了大部分场景命令行配置只是给自动化打包留的口子。5. 踩坑实录这些错误我几乎每次都见5.1 tag number over 30 is not supported这个报错在老旧项目上特别常见。它的直接诱因是 AndroidManifest 或依赖库中用到了当前构建工具无法识别的高版本 SDK 标签比如targetSdkVersion被拉到了 34而当前 AGP 或 Cordova-android 版本并不支持。解决路径分两步先看config.xml和build.gradle里的targetSdkVersion把它降回 33如果还报错就把 Cordova-android 升级到 11 及以上版本因为新版本对高版本 SDK 的支持更完整。你要是同时用了一些旧版 Cordova 插件它们编译用的 class 文件版本也可能和 Gradle 不匹配这时优先升级插件。5.2 Gradle 下载慢到怀疑人生这个问题在首次构建时几乎是绕不开的。从海外服务器下载 Gradle 发行包速度真的能让人崩溃。对策是修改gradle-wrapper.properties里的distributionUrl替换成国内源对应的 Gradle 下载地址URL 后缀的版本号要和原来保持一致。依赖库下载慢则需要在build.gradle的repositories块里把google()和mavenCentral()前面加上国内镜像地址比如阿里云的 Maven 镜像。这样依赖解析速度会明显提升。改完仓库配置后重新同步一次 Gradle基本就能顺利拉取。5.3 图标和启动画面不生效这类问题多半是资源目录对不上。Cordova 默认读取的图标目录和 Android 原生工程要求的目录可能不一致导致你换了图标但桌面显示还是默认的机器人图。解决办法是在config.xml里显式声明icon srcres/icon.png densitymdpi / icon srcres/icon_hd.png densityhdpi /或者直接手动替换app/src/main/res/mipmap-*目录下对应文件清掉 Android Studio 的缓存后重新构建。启动画面如果设置后不生效多半是主题里没有引用对应的启动图样式需要检查res/values/styles.xml里的windowSplashScreen或 Cordova 的启动屏插件配置。5.4 测试机连不上 / 模拟器识别不到电脑明明连了手机Android Studio 却显示 “No Devices”。先别急着怀疑数据线打开终端执行adb devices如果列表为空先确认手机的开发者选项和 USB 调试已经打开再确认ANDROID_HOME/platform-tools已经加入 PATH。部分国产手机默认的 USB 模式是“仅充电”需要手动切到“文件传输”才会被 ADB 识别还有的手机第一次连接会弹一个“允许 USB 调试吗”的对话框不点允许就一直不上线。模拟器识别不到一般是 AVD 启动异常。可以试着重启模拟器或者检查 SDK Manager 里系统镜像是否安装完整。我遇到过多次“模拟器起来但 AS 看不到”的情况最后发现是 HAXM/WHPX 虚拟化驱动没装好换个支持硬件的镜像版本解决。5.5 打包后游戏白屏或黑屏APK 装进手机点开就白屏这是 MV 打包时最让人头疼的问题。大部分原因是assets/www目录资源不完整比如音频资源被系统按文件名排序时路径错误、某个图片文件超过 WebView 的加载限制、或者本地存储权限没给到位。排查技巧是用 Chrome 远程调试手机打开 USB 调试用chrome://inspect打开调试面板找到你的 WebView 页面直接看 Console 里报了什么错。如果提示资源 404基本就是 www 目录漏文件如果是某个脚本语法错误多半是插件冲突或 MV 版本与 WebView 兼容性问题可以在main.js里把游戏分辨率调低做对照测试。6. 之后还能怎么扩展打包 APK 通过之后这个工程模板还能走得更远。Cordova 生态有大量现成插件可以给你的游戏加上震动反馈、头条广告、统计埋点、热更新等能力。热更新尤其适合 MV 游戏你只需要设计一个“启动时检查服务器有没有新资源包有就下载并替换 www 目录”的流程就能做到不发新 APK 也更新游戏内容前提是做好资源完整性校验不然玩家断网启动会直接黑屏。我现在的 MV 项目就一直保留着一套 Android Studio 工程模板每次游戏版本更新流程固定成三步替换 www 目录、改 versionCode、跑一次签名构建。整条链路用熟后从准备资源到拿到 APK大概只需要一支烟的功夫。最后再分享一个小经验把当初生成 keystore 时填的所有信息包括别名、密码、有效期原样存到一个纯文本文档里和 keystore 文件放在一起备份。做游戏做到后面时间最贵能在工具链上省下来的精力都是实打实加在开发进度上的。等你经历过一次“签名丢了用户无法覆盖安装”的惨案就知道这个建议值多少钱了。
Android Studio 手动打包 RPG Maker MV 游戏 APK 完整指南
做独立游戏这几年我用 Android Studio 打包 RPG Maker MV 的 apk次数多得记不清了。每次有朋友问我“官方不是有 Deploy 一键生成吗你为什么非要折腾 Android Studio”我都想拉他坐下来把打包前后那点事从头讲一遍。先说结论RPG Maker MV 官方工具确实能出包但它的最大问题是“你只能得到一个包”而不是“你能掌控这个包”。当你需要自定义包名、更换图标、调整权限、打上自己的签名或者往里面塞一点原生代码时官方一键打包基本帮不上忙。而用 Android Studio 手动打包从工程结构到最终 APK每个环节都是自己说了算。这篇内容适合三种人第一次尝试把 MV 游戏装进手机的独立开发者、想要给 MV 游戏加自定义功能的进阶用户以及被官方打包体积和包名问题折磨过的人。我会把从准备工具到生成 APK 的完整路径拆开讲附带这几年踩过的坑。1. 为什么不用官方一键打包而是折腾 Android Studio1.1 官方打包的痛点MV 官方菜单里有一个“部署”功能可以直接生成安卓 APK看似很方便。但用过的朋友应该都有体会第一生成出来的 APK 体积偏大因为里面塞了很多通用引擎文件第二包名默认是 com.rpgmakermv.xxxx 这种形式上架、更新、统计 SDK 接入时都很别扭第三图标、启动画面、屏幕方向这些参数只能填几个预设值想精细控制相当麻烦。更关键的是官方工具生成的工程是一个黑盒。你没办法在里面对 WebView 做额外的原生处理也没法利用 Android 端的调试工具去排查白屏、加载缓慢这类问题。等游戏做大了你会发现这种“闭门造车”式的打包方式根本撑不住需求。相比之下用 Android Studio 打开的是一个标准 Android 工程主 Activity、WebView 配置、Manifest、Gradle 脚本全都摊在你面前想改哪里改哪里。1.2 手动打包真正的优势手动打包并不是为了炫技而是为了拿到三样东西可控性、可调试性、可持续交付。可控性体现在签名和包名上。你自己生成 keystore自己决定 applicationId后续每次更新都用同一个签名用户安装升级包时不会出现“签名不一致无法覆盖安装”的问题。官方一键打包虽然也能签名但整个流程不够透明出问题很难排查。可调试性更重要。MV 游戏本质上是跑在 WebView 里的网页游戏用 Android Studio 打包后你可以通过 Chrome 的远程调试工具直接查看游戏页面的控制台报错、网络请求和渲染状态。这个能力在官方一键打包里几乎用不上但在手动打包里几乎是白送的——这会让你在处理白屏、脚本报错、资源加载失败时省下大量时间。可持续交付解决的是后续更新问题。手动打包意味着你有一个稳定的工程模板下次游戏更新时只需要替换 www 资源目录、改一下版本号、重新签名打包整个流程异常顺畅不必每次都重新点一遍官方工具。2. 开工前的工具准备JDK、Android Studio 与常见坑2.1 版本匹配是我踩过最大的坑很多人在第一步就卡住了不是不会装软件而是装完之后工程同步报错。最典型的就是 “Unsupported class file major version 61” 这类错误看到它基本可以判断是 JDK 版本和 Gradle 版本不匹配。我的建议是直接使用 Android Studio 自带的 JBRJetBrains Runtime不要在系统里单独装一个 Oracle JDK 然后在项目里乱改路径。Android Studio 在安装时会自带与当前版本匹配的 JBR你只需要在 “Project Structure → SDK Location” 里确认 Gradle 的 JDK 指向它就行。这样能规避掉大半版本兼容性问题。如果你非要自己装 JDK那就记住一个相对稳妥的组合JDK 17 配 Gradle 8.0 以上、Android Gradle Plugin 8.0 以上。老版本 JDK 8 配新版本 AGP 会直接报错新版本 JDK 21 配旧版本 Gradle 也会踩坑所以别跟版本较劲用 IDE 默认的就好。2.2 SDK 平台与构建工具的安装打开 Android Studio 的 SDK Manager建议至少安装两样东西一个较新版本的 Android SDK Platform比如 API 34以及对应版本的 SDK Build-Tools。很多朋友问“Android Studio SDK 无法勾选怎么办”原因一般是下载源不稳定导致列表加载不全。这种情况可以先把 SDK 列表刷新几次或者检查一下本机网络环境如果一直失败可以改用国内镜像源在 SDK Manager 的 “SDK Update Sites” 里手动添加一个可访问的镜像地址这样下载 Platform-Tools 和 Build-Tools 会顺畅很多。这里还要提一个细节构建工具版本不是越高越好要和工程里 compileSdkVersion 的数值配套。比如 targetSdkVersion 用的 33那 Build-Tools 用 33.0.0 或 34.0.0 都行如果 build 过程中出现和 tag number 相关的报错往往就是构建工具版本不匹配导致的这个我后面会专门讲。2.3 第一次启动别慌环境变量与路径Android Studio 安装完成后第一次新建或导入工程会有比较长的下载过程因为它要拉取 Gradle 和依赖库。如果你只是在命令行里用 cordova 生成工程不在 Android Studio 里编译那环境变量只需要配一个JAVA_HOME或者直接用 IDE 内置 JDK如果要在命令行里跑 Gradle 打包那ANDROID_HOME环境变量也得配上指向 SDK 的安装目录。我个人经验是宁可把环境变量配好也不要用 IDE 里的图形界面猜ANDROID_HOME指向/Users/你的用户名/Library/Android/sdkMac或C:\Users\你的用户名\AppData\Local\Android\SdkWindows然后在PATH里加上%ANDROID_HOME%\platform-tools和%ANDROID_HOME%\tools。这样后续使用adb、aapt这类命令行工具会方便很多。3. 把 MV 项目变成 Android 工程核心实操3.1 拿到游戏的 www 目录MV 游戏的所有核心资源都集中在项目根目录下的www文件夹里index.html、js、img、audio、data、fonts全都装在这里。这个目录本质上就是浏览器版本里加载的全部内容是后续打进 APK 的关键。当你用 MV 编辑器打开项目在“部署”选项里选择“Android / iOS”编辑器会生成一个包含 www 的部署目录。但你完全可以不用这个功能直接打开游戏项目的根目录把www整个复制出来。唯一需要注意的是部署目录里的 www 会带上平台相关的配置如果你已经做了移动端适配直接用原始 www 即可如果还没适配建议先在 PC 浏览器里把移动端 UI 和字体大小调好再复制 www。小技巧复制 www 时把save目录一起带上不过要注意安卓端 WebView 的存档路径可能和电脑端不同最好在测试机上多验证几次存档和读档别等玩家报告丢存档才排查。3.2 用 Cordova 创建最省事的壳MV 游戏在安卓上跑起来需要一个壳——本质上就是一套 Android 原生工程里面内置一个 WebView 来加载本地 index.html。目前最省事的方式是用 Cordova 生成这个壳。先确保本机装好了 Node.js然后全局安装 Cordovanpm install -g cordova接着创建一个空白工程cordova create mvstage com.example.mygame MyGame cd mvstage cordova platform add android这里解释一下刚才那条命令中的三段参数mvstage是文件夹名com.example.mygame是你想要的包名MyGame是显示在桌面的应用名。包名最好提前想好后面虽然在 Android Studio 里也能改但不如一开始就定准。cordova platform add android执行后会在platforms/android目录下生成一个完整的 Android Studio 工程。这个工程就是我们要操作的对象。如果你不想用命令行打包到这里就可以关掉终端、打开 Android Studio 了。3.3 替换 www 并配置 config.xmlCordova 生成的工程里默认的网页资源位于platforms/android/app/src/main/assets/www。我们直接把这个目录里的内容删掉把之前准备好的 MV 项目www整个复制进去。这一步最怕文件缺失因为 MV 的资源文件特别多复制时如果因为路径过长或文件名特殊字符导致漏文件游戏运行起来就会黑屏。我的习惯是复制完成后再对一遍文件和大小确保总数一致。接下来改config.xml这个文件在工程根目录下是 Cordova 的全局配置。重点设置这几个项preference nameOrientation valueportrait / preference nameFullscreen valuetrue / preference nameBackgroundColor value0xff000000 / preference nameandroid-minSdkVersion value21 / preference nameandroid-targetSdkVersion value33 /如果你是横屏游戏把Orientation改成landscape或者删掉这一行让它支持自由旋转。Fullscreen设为true会隐藏系统状态栏沉浸感更强BackgroundColor是游戏加载时的背景色设成黑色能避免加载期间出现白屏闪烁。还有一个容易被忽略的配置allow-navigation。如果你的游戏内嵌了远程网页链接或者需要加载在线资源得在这里声明允许跳转的域名纯本地游戏这一项可以不配。4. 在 Android Studio 里完成打包4.1 打开工程并认识关键界面用 Android Studio 打开platforms/android目录点开之后等待 Gradle 同步。第一次同步时间通常比较长因为它要下载项目声明的依赖。如果同步卡在 Gradle 下载那一环我建议去改gradle/wrapper/gradle-wrapper.properties里的distributionUrl把下载地址换成速度更快的国内镜像源指向对应版本号的文件即可。同步成功后你会看到左侧项目结构里有一个app模块和一个cordovaLib模块。app就是你的应用主模块所有业务相关的改动都集中在这里cordovaLib是 Cordova 提供的运行库一般情况下不需要动它。在app模块下重点关注两个地方src/main/AndroidManifest.xml和build.gradle。前者声明应用的包名、权限和入口 Activity后者控制编译版本、依赖和签名配置。MV 游戏要联网就检查INTERNET权限要本地读写就检查WRITE_EXTERNAL_STORAGE不过高版本安卓对存储权限管得严最好在运行时动态申请或者直接让游戏只使用 WebView 的本地存储。4.2 包名、图标与版本号调整如果你在cordova create时已经写清楚包名那么 AndroidManifest 里的package属性和build.gradle里的applicationId应该是一致的。没写清楚也没关系现在手动改也来得及以build.gradle里applicationId为准AndroidManifest 里不要设package冲突值。版本号在build.gradle里处理versionCode 1 versionName 1.0.0versionCode必须是数字每次更新递增商店和系统靠它判断版本新旧versionName是展示给用户看的字符串想写什么写什么。很多人把这两个搞混结果发了三次包用户永远提示“已是最新版本”其实就是 versionCode 没变。图标和启动屏一般放在app/src/main/res目录下按mipmap-mdpi、mipmap-hdpi、mipmap-xhdpi、mipmap-xxhdpi、mipmap-xxxhdpi分目录放不同分辨率的图片。没有特殊要求的话一套 512×512 的图标缩放到各目录即可有启动屏需求的在res/drawable或splash目录里放好图片并在config.xml里声明SplashScreen相关偏好。注意安卓 12 及更高版本强制使用系统自带的应用图标样式过于复杂的圆形图标可能会被系统裁切设计时给图标周围留点安全边距。4.3 生成签名 APK 的方法打开 Android Studio 菜单栏的Build → Generate Signed Bundle or APK选择APK。如果还没有 keystore就点击Create new...新建一个填写好别名、密码、证书有效期这些信息。这里有个最容易让人后悔的细节keystore 文件一旦丢失或密码遗忘你以后永远无法用同一个签名发布更新包。到时候用户只能先卸载旧版再装新版存档全部丢失那场面相当难堪。所以生成 keystore 后加密备份到网盘和本地至少两个地方密码也单独记录。签名配置完成后选择release构建版本点击 Finish。等到底部 Gradle 任务跑完APK 会输出到app/build/outputs/apk/release/目录下。这个 APK 是带签名的正式包可以发给测试人员安装也可以直接上传应用市场。构建过程中如果遇到需要额外配置的签名信息也可以在build.gradle里的android块下添加signingConfigs节点不过图形界面操作已经覆盖了大部分场景命令行配置只是给自动化打包留的口子。5. 踩坑实录这些错误我几乎每次都见5.1 tag number over 30 is not supported这个报错在老旧项目上特别常见。它的直接诱因是 AndroidManifest 或依赖库中用到了当前构建工具无法识别的高版本 SDK 标签比如targetSdkVersion被拉到了 34而当前 AGP 或 Cordova-android 版本并不支持。解决路径分两步先看config.xml和build.gradle里的targetSdkVersion把它降回 33如果还报错就把 Cordova-android 升级到 11 及以上版本因为新版本对高版本 SDK 的支持更完整。你要是同时用了一些旧版 Cordova 插件它们编译用的 class 文件版本也可能和 Gradle 不匹配这时优先升级插件。5.2 Gradle 下载慢到怀疑人生这个问题在首次构建时几乎是绕不开的。从海外服务器下载 Gradle 发行包速度真的能让人崩溃。对策是修改gradle-wrapper.properties里的distributionUrl替换成国内源对应的 Gradle 下载地址URL 后缀的版本号要和原来保持一致。依赖库下载慢则需要在build.gradle的repositories块里把google()和mavenCentral()前面加上国内镜像地址比如阿里云的 Maven 镜像。这样依赖解析速度会明显提升。改完仓库配置后重新同步一次 Gradle基本就能顺利拉取。5.3 图标和启动画面不生效这类问题多半是资源目录对不上。Cordova 默认读取的图标目录和 Android 原生工程要求的目录可能不一致导致你换了图标但桌面显示还是默认的机器人图。解决办法是在config.xml里显式声明icon srcres/icon.png densitymdpi / icon srcres/icon_hd.png densityhdpi /或者直接手动替换app/src/main/res/mipmap-*目录下对应文件清掉 Android Studio 的缓存后重新构建。启动画面如果设置后不生效多半是主题里没有引用对应的启动图样式需要检查res/values/styles.xml里的windowSplashScreen或 Cordova 的启动屏插件配置。5.4 测试机连不上 / 模拟器识别不到电脑明明连了手机Android Studio 却显示 “No Devices”。先别急着怀疑数据线打开终端执行adb devices如果列表为空先确认手机的开发者选项和 USB 调试已经打开再确认ANDROID_HOME/platform-tools已经加入 PATH。部分国产手机默认的 USB 模式是“仅充电”需要手动切到“文件传输”才会被 ADB 识别还有的手机第一次连接会弹一个“允许 USB 调试吗”的对话框不点允许就一直不上线。模拟器识别不到一般是 AVD 启动异常。可以试着重启模拟器或者检查 SDK Manager 里系统镜像是否安装完整。我遇到过多次“模拟器起来但 AS 看不到”的情况最后发现是 HAXM/WHPX 虚拟化驱动没装好换个支持硬件的镜像版本解决。5.5 打包后游戏白屏或黑屏APK 装进手机点开就白屏这是 MV 打包时最让人头疼的问题。大部分原因是assets/www目录资源不完整比如音频资源被系统按文件名排序时路径错误、某个图片文件超过 WebView 的加载限制、或者本地存储权限没给到位。排查技巧是用 Chrome 远程调试手机打开 USB 调试用chrome://inspect打开调试面板找到你的 WebView 页面直接看 Console 里报了什么错。如果提示资源 404基本就是 www 目录漏文件如果是某个脚本语法错误多半是插件冲突或 MV 版本与 WebView 兼容性问题可以在main.js里把游戏分辨率调低做对照测试。6. 之后还能怎么扩展打包 APK 通过之后这个工程模板还能走得更远。Cordova 生态有大量现成插件可以给你的游戏加上震动反馈、头条广告、统计埋点、热更新等能力。热更新尤其适合 MV 游戏你只需要设计一个“启动时检查服务器有没有新资源包有就下载并替换 www 目录”的流程就能做到不发新 APK 也更新游戏内容前提是做好资源完整性校验不然玩家断网启动会直接黑屏。我现在的 MV 项目就一直保留着一套 Android Studio 工程模板每次游戏版本更新流程固定成三步替换 www 目录、改 versionCode、跑一次签名构建。整条链路用熟后从准备资源到拿到 APK大概只需要一支烟的功夫。最后再分享一个小经验把当初生成 keystore 时填的所有信息包括别名、密码、有效期原样存到一个纯文本文档里和 keystore 文件放在一起备份。做游戏做到后面时间最贵能在工具链上省下来的精力都是实打实加在开发进度上的。等你经历过一次“签名丢了用户无法覆盖安装”的惨案就知道这个建议值多少钱了。
