主题
Skip to content 
代理分包资源构建
背景：该模块用于给代理包提供 Cocos Creator 分包资源支持。之前插件只处理资源混淆，现在可以把指定 Bundle 按加密远程分包资源处理，并在构建时自动完成混淆。
核心规则：
- 工程中的游戏 Bundle 都不要勾选「配置为远程包」。
- 在项目根目录
package.json中通过subpackages字段声明需要插件处理的分包 Bundle 名称。 - 写入
subpackages的 Bundle 会被插件按远程分包资源混淆；没有写入的 Bundle 按内置 Bundle 处理。 - 混淆后的分包资源可以上传到服务器加载，也可以按 AAB/APK/IPA 分包要求放入指定目录后用全路径加载。
WARNING
subpackages 中填写的是工程中配置的 Bundle 名称，不是分包资源目录路径，也不是服务器 URL。
导入插件
在 Cocos Creator 工程根目录创建 extensions 目录，解压 ccgame-encry.zip 到该目录下，并将插件目录命名为 ccgame-encry。
WARNING
插件安装完成后需要重启 Cocos Creator 编辑器，确保插件被正确加载。
Mac 权限处理
如果 Mac 第一次运行插件失败，需要给插件内置的执行文件添加可执行权限：
bash
chmod +x /aaa/bbb/cc/extensions/ccgame-encry/static/macOS/node
chmod +x /aaa/bbb/cc/extensions/ccgame-encry/static/macOS/assetshandler其中 /aaa/bbb/cc 替换为实际 Cocos Creator 工程路径。
配置 Bundle
在 Cocos Creator 中配置需要分包的 Bundle 名称。后续 package.json.subpackages 里填写的就是这里配置的 Bundle 名称。
WARNING
所有游戏 Bundle 都不要勾选「配置为远程包」。远程分包逻辑由加密插件根据 package.json.subpackages 接管。
配置分包信息
在 Cocos Creator 项目根目录的 package.json 中增加 subpackages 字段，声明需要混淆并作为分包资源处理的 Bundle 名称。
json
{
"name": "test3",
"uuid": "d63c4fdc-5ea0-4771-82e7-5b0e91d68",
"subpackages": ["bundle1", "bundle2"],
"creator": {
"version": "3.7.2"
}
}TIP
如果工程里配置的 Bundle 名称是 bundle2，这里就填写 bundle2。不要填写 remote/bundle2、构建产物目录名或 CDN 地址。
构建资源
在 Cocos Creator 中选择 Android 或 iOS 构建资源时，插件会自动对资源进行混淆，并处理 subpackages 中声明的 Bundle。
构建完成后，需要关注产物中的以下目录：
game_resources：混淆后的游戏资源根目录，出包时按平台放入工程模板资源目录。remote：混淆后的分包资源目录，可上传服务器，也可按 AAB/APK/IPA 分包目录要求放入指定位置。subpackages：构建生成的分包信息目录，用于确认分包资源是否被正确处理。
WARNING
不要把未混淆的原始 Bundle 资源上传或放入线上包体。线上使用的分包资源应来自构建产物中的混淆后 remote 目录。
游戏中加载 Bundle
远程服务器 Bundle
如果分包资源放在远程服务器，assetManager.loadBundle 传入对应的 HTTP/HTTPS 地址即可。
ts
assetManager.loadBundle("https://your-cdn.example.com/remote/bundle2", (err, bundle) => {
if (err) {
console.error("load remote bundle failed", err);
return;
}
console.log("load remote bundle success", bundle);
});内置 Bundle
没有写入 subpackages 的 Bundle 会按内置 Bundle 处理，运行时直接传 Bundle 名称加载。
ts
assetManager.loadBundle("bundle1", (err, bundle) => {
if (err) {
console.error("load bundle failed", err);
return;
}
console.log("load bundle success", bundle);
});指定目录 Bundle
如果资源既不走远程服务器，也不是 Creator 内置 Bundle，而是放在缓存目录、APK、IPA 或 AAB 分包中的某个目录，需要把构建出的混淆后分包资源放到指定目录，并在加载时传入完整路径。
Android assets/assets 目录可使用 @assets/xxx 格式。例如 AAB 分包资源放在 assets/assets/fighting 时：
ts
assetManager.loadBundle("@assets/fighting", (err, bundle) => {
if (err) {
console.error("load path bundle failed", err);
return;
}
console.log("load path bundle success", bundle);
});WARNING
安卓 AAB 分包场景中，资源通常放在工程的 assets/assets 目录下。需要先构建出混淆后的远程分包资源，再把对应 Bundle 目录放到 AAB 要求的位置，加载时路径要指向具体的 Bundle 目录。
更多 Bundle 加载规则可参考 Cocos Creator Asset Bundle 文档。
出包注意事项
加密混淆后的资源出包时，需要按 资源加密出包 接入解密库和解密代码，否则包体无法正常运行。
资源放置规则：
- Android：将处理后的
game_resources放入工程模板的assets目录下。 - iOS：将处理后的
game_resources放入工程模板的Resources目录下。 - 远程服务器分包：上传构建产物根目录下的
remote到资源服务器，运行时使用 URL 加载。 - AAB/APK/IPA 目录分包：将
remote中对应 Bundle 的混淆资源放到指定目录，运行时使用完整路径加载。
WARNING
如果使用远程服务器加载分包，出包前需要删除 game_resources/remote，避免远程分包资源随包体发布。若是 AAB/APK/IPA 目录分包，则按平台要求把对应 Bundle 放入指定目录。
验证清单
发布前按以下清单检查：
ccgame-encry插件已安装到extensions目录，并重启过编辑器。- Mac 环境下插件内置
node和assetshandler已添加可执行权限。 - Cocos Creator 中 Bundle 名称与
package.json.subpackages中填写的名称一致。 - 游戏 Bundle 没有勾选「配置为远程包」。
- 构建后产物根目录已生成
remote目录，并包含对应 Bundle 的混淆资源。 - 远程服务器分包已将
remote中的资源上传到服务器，并确认 URL 可访问。 - AAB/APK/IPA 目录分包已将对应 Bundle 放入指定目录，并确认加载路径指向具体 Bundle 目录。
- 游戏运行时代码按资源位置选择 URL、Bundle 名称或完整路径加载。
- 出包工程已按 资源加密出包 接入解密库和解密代码。
常见问题
subpackages 应该填什么？
填写工程中配置的 Bundle 名称，例如 bundle1、bundle2。不要填写 remote/bundle2、构建产物目录名或服务器 URL。
为什么 Bundle 不勾选「配置为远程包」？
这里的远程分包逻辑由加密插件根据 package.json.subpackages 接管。勾选 Creator 自带的远程包配置后，构建路径和插件处理逻辑容易不一致，可能导致资源没有按预期混淆。
哪些 Bundle 会作为内置 Bundle？
没有配置到 subpackages 的 Bundle 会作为内置 Bundle，随 game_resources 放入包体，运行时直接使用 Bundle 名称加载。
AAB 分包怎么加载？
先使用插件构建出混淆后的分包资源，再把 remote 中对应 Bundle 目录放到 AAB 指定的 assets 目录结构下。运行时使用 @assets/xxx/xxx 这类完整路径加载，并且路径要指向具体 Bundle 目录。
运行时加载失败怎么排查？
先确认当前 Bundle 属于远程服务器、内置 Bundle 还是指定目录加载，再分别检查 URL、Bundle 名称或完整路径是否正确。若资源已经混淆，还需要确认出包工程已正确接入 资源加密出包 中的解密库和解密代码。
