企业官网建设流程全解析

1. 项目概述：为什么我们需要自定义构建模板？

在Cocos Creator项目开发中，尤其是涉及到原生平台（如Android、iOS）的发布时，我们经常会遇到一个令人头疼的瓶颈：构建后的原生工程配置文件是“只读”的。引擎的构建流程会生成一个标准的、符合通用场景的原生工程，但现实中的项目需求千差万别。你可能需要修改Android的build.gradle来引入特定的Maven仓库，或者调整iOS的Info.plist以添加自定义的权限描述，又或者需要修改AndroidManifest.xml中的某些Activity属性。如果每次都手动去构建输出的build目录下修改这些文件，不仅效率低下，更致命的是，一旦执行了“构建”或“构建并运行”操作，你所有的手动修改都会被引擎的构建流程无情地覆盖掉，前功尽弃。

这正是“自定义构建模板”功能存在的核心价值。它不是一个高级的、遥不可及的特性，而是解决上述痛点的标准答案。简单来说，它允许我们在项目目录中预先放置一份“模板”，当Cocos Creator执行构建时，不是从零生成所有原生文件，而是以我们的模板为基础进行生成。这样，我们对原生工程配置文件的任何定制化修改，都能被“固化”下来，在每次构建时自动生效，一劳永逸。这不仅仅是修改几个参数，更是将项目与特定平台SDK集成、实现复杂构建流程自动化、确保团队协作环境一致性的基石。无论你是需要集成第三方广告SDK、推送服务，还是进行深度性能调优，自定义构建模板都是你必须掌握的技能。

2. 核心思路与模板结构解析

2.1 自定义构建模板的工作原理

Cocos Creator的构建系统可以理解为一个精密的“文件复制与替换”引擎。当你不使用自定义模板时，它从一个内置的、不可见的“默认模板库”中复制文件到构建输出目录。而启用自定义模板后，构建系统会优先在你的项目目录中寻找同名的模板文件。如果找到了，就使用你的；如果没找到，则回退到使用内置的默认文件。

这个机制决定了我们的操作核心：在正确的位置，放置正确的文件，并修改正确的内容。整个过程是声明式的，我们无需编写复杂的构建脚本去干预流程，只需要提供“原料”（模板文件），构建系统会自动完成“烹饪”（文件生成与变量替换）。

2.2 模板目录结构与关键文件

自定义模板的根目录位于你的Cocos Creator项目根目录下的build-templates文件夹。其内部结构必须严格对应目标平台，因为不同平台的原生工程结构完全不同。

your-cocos-project/ ├── assets/ ├── build/ ├── build-templates/ # 自定义构建模板根目录 │ ├── android/ # Android平台模板 │ │ ├── AndroidManifest.xml │ │ ├── app/ # 对应Android Studio项目中的app模块 │ │ │ ├── build.gradle │ │ │ ├── proguard-rules.pro │ │ │ └── src/main/ # 放置Java源代码、资源等 │ │ │ ├── java/ │ │ │ ├── res/ │ │ │ └── assets/ │ │ └── gradle.properties │ ├── ios/ # iOS平台模板 │ │ ├── Info.plist │ │ ├── Podfile │ │ └── 你的工程名.xcodeproj/project.pbxproj (谨慎修改) │ └── jsb-default/ # 各平台共用的JSB相关配置模板 │ └── frameworks/ └── settings/

关键文件说明：

1. AndroidManifest.xml (Android): 应用的“身份证”和“权限声明书”。定义应用包名、组件（Activity、Service）、所需权限（如网络、存储）、硬件特性等。这是最常需要修改的文件之一。
2. app/build.gradle (Android): 项目的构建脚本。控制编译SDK版本、依赖库引入（如implementation ‘com.xxx:yyy:1.0.0‘）、签名配置、构建变体等。集成任何第三方SDK几乎都要动它。
3. gradle.properties (Android): Gradle构建的全局属性文件。可以设置JVM内存大小、启用并行构建等优化选项。
4. Info.plist (iOS): 类似于AndroidManifest，定义iOS应用的名称、版本、权限、支持的设备方向、URL Scheme等。
5. Podfile (iOS): CocoaPods依赖管理文件。用于声明项目需要引入哪些第三方原生库（如Firebase、Adjust）。
6. project.pbxproj (iOS): Xcode工程文件。结构复杂，自动化修改风险高，通常不建议直接在此模板中修改，除非有非常特殊的需求。

注意：build-templates目录下的文件并不是全部都需要你提供。你只需要放置你需要修改的那个或那几个文件即可。构建系统会采用“合并”策略：对于你提供的文件，完全使用你的版本；对于你没提供的文件，则使用内置默认版本。这给了我们极大的灵活性。

2.3 模板中的变量替换

这是自定义模板的“灵魂”功能。你不可能在模板里写死包名、应用名或版本号，因为这些信息来自Cocos Creator项目设置。Cocos Creator构建时，会将模板中的特定占位符替换为实际值。

常见变量示例：

• ${packageName}: 替换为项目设置中填写的应用包名（如com.company.game）。
• ${appName}: 替换为项目设置中的应用名称。
• ${orientation}: 替换为设定的屏幕方向（如landscape）。
• ${versionName},${versionCode}: 替换为应用版本名称和版本代码。

你可以在模板文件中像下面这样使用它们：

AndroidManifest.xml 示例片段：

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="${packageName}"> <application android:label="${appName}" android:icon="@mipmap/icon" ... >

build.gradle 示例片段：

android { defaultConfig { applicationId "${packageName}" versionName "${versionName}" versionCode ${versionCode} } }

构建时，${packageName}等会被自动替换，使得一份模板能适应不同配置的项目。

3. 实战：修改Android原生工程配置

3.1 场景一：集成第三方SDK（以广告SDK为例）

假设我们需要集成一个名为AwesomeAd的SDK，它要求我们：

1. 在build.gradle中添加Maven仓库和依赖。
2. 在AndroidManifest.xml中添加权限和必要的组件声明。

步骤1：创建并修改模板文件

首先，在项目根目录创建模板结构。最安全的方式是先从一次标准构建的输出中复制你需要修改的文件。

1. 在Cocos Creator编辑器中，先进行一次普通的Android平台构建（构建路径例如build/android）。
2. 从build/android/proj/app/目录下，找到AndroidManifest.xml和build.gradle文件。
3. 在项目根目录创建build-templates/android/目录，并将这两个文件复制到对应位置：
   • build-templates/android/AndroidManifest.xml
   • build-templates/android/app/build.gradle

步骤2：编辑build.gradle模板

打开build-templates/android/app/build.gradle，我们通常在dependencies块中添加SDK依赖。

android { // ... 其他配置 } dependencies { // Cocos Creator 运行时依赖，不要删除 implementation fileTree(dir: '../java/libs', include: ['*.jar']) implementation fileTree(dir: 'libs', include: ['*.jar']) // 添加 AwesomeAd SDK 依赖 // 假设该SDK托管在特定的Maven仓库 implementation 'com.awesome:ad-sdk:2.1.0' // 可能还需要添加一些支持库 implementation 'androidx.appcompat:appcompat:1.3.0' }

有时SDK需要添加额外的Maven仓库。这需要修改项目级的build.gradle，但自定义模板只提供了app/build.gradle。别急，Cocos Creator允许我们自定义项目级模板，它位于build-templates/android/build.gradle（注意，与app/build.gradle同级）。你可以从构建输出的build/android/proj/build.gradle复制并修改其allprojects/repositories块。

步骤3：编辑AndroidManifest.xml模板

打开build-templates/android/AndroidManifest.xml，添加必要的权限和组件。

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="${packageName}"> <!-- 添加网络权限，广告SDK通常需要 --> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- 如果需要访问设备标识，可能需要这个（注意隐私政策） --> <uses-permission android:name="android.permission.READ_PHONE_STATE" /> <application android:label="${appName}" ... > <!-- 添加 AwesomeAd SDK 所需的 Activity --> <activity android:name="com.awesome.ads.FullScreenAdActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen" android:configChanges="keyboard|keyboardHidden|orientation|screenSize" /> <!-- 添加 SDK 所需的 Service 或 Receiver --> <service android:name="com.awesome.ads.AdService" /> </application> </manifest>

步骤4：验证构建

完成修改后，回到Cocos Creator，清理之前的构建（删除build/android文件夹），然后重新构建。构建完成后，检查build/android/proj/app/build.gradle和AndroidManifest.xml，确认你的修改已经生效。

实操心得：集成SDK时，最棘手的往往是依赖冲突。如果构建失败，报错信息中出现了Duplicate class或Conflict with dependency，通常是因为Cocos Creator内置的库或你添加的其他SDK包含了相同库的不同版本。这时需要在build.gradle中使用exclude或强制指定版本号resolutionStrategy来解决冲突。这是一个需要耐心排查的常见坑点。

3.2 场景二：配置应用签名与构建变体

发布应用必须使用正式的签名密钥。我们绝不应该在构建后才手动签名，而应该让构建流程自动完成。

步骤1：准备签名文件

将你的.jks或.keystore签名文件放入项目目录中，例如创建一个signing文件夹来管理。切记将这个文件夹路径加入.gitignore，不要将密钥提交到代码仓库！

步骤2：在模板中配置签名信息

修改build-templates/android/app/build.gradle，在android块中添加signingConfigs和buildTypes。

android { signingConfigs { release { // 这些信息建议通过环境变量或单独的属性文件读取，此处为演示直接写入。 // 安全做法：将storePassword和keyPassword移至gradle.properties（不提交到仓库） // 或使用环境变量。 storeFile file("../../signing/your_keystore.jks") // 相对路径指向项目内的密钥文件 storePassword "your_store_password" keyAlias "your_key_alias" keyPassword "your_key_password" } } buildTypes { debug { // 调试模式配置 signingConfig signingConfigs.debug // 默认使用debug签名 debuggable true } release { // 发布模式配置 minifyEnabled true // 启用代码混淆 proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' signingConfig signingConfigs.release // 使用我们配置的release签名 debuggable false } } }

更安全的密码管理方式：

1. 在项目根目录创建keystore.properties文件（加入.gitignore）：

   storePassword=your_real_store_password keyPassword=your_real_key_password

2. 在build.gradle顶部读取：

   def keystorePropertiesFile = rootProject.file("../../keystore.properties") def keystoreProperties = new Properties() if (keystorePropertiesFile.exists()) { keystoreProperties.load(new FileInputStream(keystorePropertiesFile)) }

3. 在signingConfigs中引用：

   storePassword keystoreProperties['storePassword'] keyPassword keystoreProperties['keyPassword']

步骤3：配置构建变体（Flavors）

如果你需要为不同渠道打包不同包名或应用ID的应用，可以使用productFlavors。

android { flavorDimensions "channel" productFlavors { googleplay { dimension "channel" // 可以为不同渠道设置不同的applicationId后缀 applicationIdSuffix ".google" // 可以定义不同的资源或配置 manifestPlaceholders = [CHANNEL_VALUE: "googleplay"] } huawei { dimension "channel" applicationIdSuffix ".huawei" manifestPlaceholders = [CHANNEL_VALUE: "huawei"] } } }

然后在AndroidManifest.xml中，可以使用占位符${CHANNEL_VALUE}来接收这个值，用于统计等用途。

<meta-data android:name="CHANNEL" android:value="${CHANNEL_VALUE}" />

在Cocos Creator构建面板中，构建完成后，你会在build/android目录下看到googleplayRelease、huaweiRelease等不同的APK输出文件夹。

4. 实战：修改iOS原生工程配置

4.1 场景一：修改Info.plist配置

iOS的配置主要集中在Info.plist文件中。常见需求包括添加隐私权限描述、自定义URL Scheme、配置后台模式等。

步骤1：获取并修改模板

同样，先进行一次标准iOS构建，从build/ios/proj/目录下找到Info.plist文件，复制到build-templates/ios/Info.plist。

步骤2：添加隐私权限描述

自iOS 10以来，访问相册、相机、地理位置等都需要在Info.plist中添加用途描述，否则会崩溃。

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <!-- Cocos Creator 自动生成的配置 --> <key>CFBundleName</key> <string>${appName}</string> <key>CFBundleIdentifier</key> <string>${packageName}</string> <!-- 添加相册访问描述 --> <key>NSPhotoLibraryUsageDescription</key> <string>我们需要访问您的相册来保存游戏截图</string> <!-- 添加相机访问描述 --> <key>NSCameraUsageDescription</key> <string>我们需要使用相机进行AR游戏功能</string> <!-- 添加地理位置访问描述（使用时） --> <key>NSLocationWhenInUseUsageDescription</key> <string>我们需要您的位置信息来提供附近的玩家匹配服务</string> <!-- 添加麦克风访问描述 --> <key>NSMicrophoneUsageDescription</key> <string>我们需要使用麦克风进行游戏语音聊天</string> <!-- 添加自定义URL Scheme --> <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>awesomegame</string> <!-- 你的自定义Scheme --> </array> </dict> </array> <!-- 配置后台模式（如音频播放） --> <key>UIBackgroundModes</key> <array> <string>audio</string> </array> <!-- 强制横屏设置（如果项目是横屏游戏） --> <key>UISupportedInterfaceOrientations</key> <array> <string>UIInterfaceOrientationLandscapeRight</string> <string>UIInterfaceOrientationLandscapeLeft</string> </array> <key>UISupportedInterfaceOrientations~ipad</key> <array> <!-- 如果需要iPad支持竖屏，可以不同 --> <string>UIInterfaceOrientationLandscapeRight</string> <string>UIInterfaceOrientationLandscapeLeft</string> </array> </dict> </plist>

4.2 场景二：使用CocoaPods管理依赖

iOS平台广泛使用CocoaPods来管理第三方库。Cocos Creator构建的iOS工程默认支持Pod。

步骤1：创建Podfile模板

从构建输出的build/ios/proj/目录复制Podfile文件到build-templates/ios/Podfile。

步骤2：编辑Podfile模板

一个典型的用于Cocos Creator游戏的Podfile模板如下：

# Cocos Creator生成的固定内容，不要修改platform和use_frameworks!之后的target platform :ios, '11.0' # 设置最低部署目标版本 use_frameworks! :linkage => :static # 建议使用静态链接，兼容性更好 target 'my-mobile-game-mobile' do # 这个target名称是固定的，由引擎生成 # 在这里添加你的Pod依赖 pod 'Firebase/Analytics' # 例如集成Firebase分析 pod 'Firebase/Crashlytics' # 集成Firebase崩溃报告 pod 'Adjust', '~> 4.32.0' # 集成Adjust归因SDK # 如果某个库只希望在Debug模式下引入 pod 'FLEX', :configurations => ['Debug'] end

步骤3：关于project.pbxproj

这是Xcode的工程文件，极其复杂且容易出错。除非你知道你在做什么（例如，需要添加特定的系统框架Framework，或者修改编译标志Other Linker Flags），否则强烈不建议直接修改此文件的模板。大部分需求可以通过修改Info.plist、Podfile或在构建后事件中添加脚本实现。

5. 高级技巧与避坑指南

5.1 条件化模板与构建参数

有时，我们可能希望根据不同的构建选项（如是否是调试模式、是否针对某个渠道）来生成略有不同的配置文件。Cocos Creator的构建模板本身不支持复杂的逻辑判断，但我们可以借助Gradle（Android）和Shell/Python脚本（iOS）来实现。

Android端（Gradle脚本）：

可以在build.gradle中读取Cocos Creator构建时传入的参数（如果构建面板有自定义参数功能，或者通过环境变量），然后动态配置buildConfigField或manifestPlaceholders。

android { defaultConfig { // 从环境变量或项目属性读取一个标志 def isChinaChannel = project.hasProperty('CHINA_CHANNEL') ? project.CHINA_CHANNEL : "false" buildConfigField "boolean", "IS_CHINA_CHANNEL", isChinaChannel // 在Manifest中使用占位符 manifestPlaceholders = [ APP_CHANNEL: project.hasProperty('APP_CHANNEL') ? project.APP_CHANNEL : "default" ] } }

然后，在Cocos Creator的构建面板中，你可以添加自定义构建参数（这需要你编写构建插件），或者在命令行构建时传入-p CHINA_CHANNEL=true。

通用方案（构建后脚本）：

一个更通用且强大的方法是使用“构建后脚本”。Cocos Creator允许在构建流程结束后执行自定义脚本。

1. 在你的项目目录下创建一个脚本文件，例如build-hooks/post-build.js。
2. 在脚本中，你可以读取构建参数，然后使用Node.js的fs模块去动态修改已经生成在build目录下的原生工程文件。
3. 在Cocos Creator的package.json中配置构建插件，注册这个后置脚本。

这种方法更灵活，可以跨平台，但实现起来也更复杂，需要对Cocos Creator的构建扩展API有一定了解。

5.2 资源与源代码的注入

除了修改配置文件，自定义模板另一个强大功能是注入自定义的原生代码和资源。

• Android Java代码：将你的.java或.kt文件放入build-templates/android/app/src/main/java/com/your/package/目录下。注意包路径要正确。
• Android资源：将图片、布局XML等放入build-templates/android/app/src/main/res/的对应子目录（如drawable-hdpi,layout）。
• iOS Objective-C/Swift代码：将.h和.m或.swift文件放入build-templates/ios/目录下。但更规范的做法是通过CocoaPods引入，或者手动在构建后脚本中将文件复制到Xcode工程中并修改project.pbxproj（不推荐新手直接操作）。
• iOS资源：将图片、故事板等放入build-templates/ios/目录，同样需要处理工程文件的引用。

5.3 常见问题与排查技巧

1. 构建失败：找不到符号或类

   • 问题：修改build.gradle添加依赖后，构建成功，但编译原生代码时失败，提示找不到第三方库的类。
   • 排查：首先检查依赖写法是否正确，版本号是否存在。然后执行一次完整的Gradle同步。在Android Studio中打开build/android/proj，点击Sync Project with Gradle Files。查看app/build.gradle文件是否已正确包含你的依赖。对于iOS，在终端进入build/ios/proj目录，运行pod install --repo-update。

2. 修改不生效

   • 问题：修改了模板文件，重新构建后，发现build目录下的对应文件没有变化。
   • 排查：
     • 确认模板文件放在了正确的路径下（build-templates/<platform>/...）。
     • 确认文件名和大小写完全正确。
     • 清理构建：Cocos Creator的构建系统有缓存。最可靠的方法是：在构建面板中点击构建按钮旁边的下拉箭头，选择清理构建，或者直接手动删除整个build文件夹，然后重新构建。

3. Android Manifest合并冲突

   • 问题：构建失败，报错Manifest merger failed。
   • 排查：这通常是因为你模板中的AndroidManifest.xml与某个引入的第三方库（AAR）中的清单文件存在属性冲突。常见的冲突有android:theme、android:allowBackup、uses-sdk等。
   • 解决：在app/build.gradle的android块中添加合并规则，或使用tools:replace、tools:ignore属性。例如：

     android { defaultConfig { // ... } // 在构建时忽略指定的清单合并错误 lintOptions { abortOnError false checkReleaseBuilds false } }

     在AndroidManifest.xml的application标签中：

     <application ... tools:replace="android:theme,android:allowBackup" tools:ignore="GoogleAppIndexingWarning">

4. iOS构建成功但运行崩溃（权限问题）

   • 问题：应用在启动时立即崩溃，控制台日志提示This app has crashed because it attempted to access privacy-sensitive data without a usage description.
   • 排查：这是典型的缺少隐私权限描述。仔细检查Info.plist文件，确保你使用了所有所需权限对应的描述键（如NSCameraUsageDescription），并且其值<string>非空。

5. 如何调试模板本身

   • 最直接的方法是在模板文件中加入一些明显的注释或标识，构建后检查输出文件，看你的修改是否被包含。对于复杂的逻辑，可以编写简单的构建后脚本来打印日志，检查构建过程中的变量和路径。

自定义构建模板是Cocos Creator进阶开发必须跨越的一道坎。它初看有些繁琐，但一旦设置完成，就能将繁琐的原生工程配置工作自动化、标准化，极大提升团队协作效率和项目维护性。从修改一个简单的权限描述，到集成一套复杂的SDK生态，其核心思想都是一致的：将变化的部分抽象成模板，让构建流程为你重复劳动。掌握它，你就能真正驾驭Cocos Creator的原生发布流程。