v2.4 定制项目构建流程升级指南

文：Santy-Wang、Xunyi0

本文将详细介绍定制过项目构建流程的旧项目升级到 v2.4 时的注意事项。从 v2.4 开始，我们对项目构建流程做出了一些调整，事件回调时传入的参数也做了一定的改动。如果开发者在 v2.4 之前，有根据文档 定制项目构建流程 对项目进行过扩展，注册了 before-change-files、build-finished 事件来定制项目构建流程，那么：

  • 对 美术策划 而言，项目中的所有资源，例如场景、动画、Prefab 都不需要修改，也不用升级。
  • 对 程序 而言，影响主要体现在需要修改扩展包中注册事件的回调函数的参数。

升级步骤

  • 备份旧项目的插件扩展包。
    • 全局（所有项目）插件扩展包位于 C:\Users\用户\.CocosCreator\packages 目录（Windows）或者 用户/.CocosCreator/packages 目录（Mac）。
    • 单个项目专用插件扩展包位于项目的 packages 目录下。
  • 打开代码编辑器，进行代码升级。

参数变化

事件回调时传入的参数 options 中 不再有 buildResults，而是提供了一个 bundles 数组。

  1. // 修改前
  2. function onBeforeBuildFinish (options, callback) {
  3.     var prefabUrl = 'db://assets/cases/05_scripting/02_prefab/MonsterPrefab.prefab';
  4.     var prefabUuid = Editor.assetdb.urlToUuid(prefabUrl);
  6.     // 通过 options.buildResults 访问 BuildResults
  7.     var buildResults = options.buildResults;
  8.     // 获得指定资源依赖的所有资源
  9.     var depends = buildResults.getDependencies(prefabUuid);
  11.     for (var i = 0; i < depends.length; ++i) {
  12.         var uuid = depends[i];
  13.         // 获得项目中的资源相对 URL（如果是自动图集生成的图片，由于项目中不存在对应资源，将返回空）
  14.         var url = Editor.assetdb.uuidToUrl(uuid);
  15.         // 获取资源类型
  16.         var type = buildResults.getAssetType(uuid);
  17.         // 获得项目中的资源绝对路径（如果是自动图集生成的图片，同样将返回空）
  18.         var rawPath = Editor.assetdb.uuidToFspath(uuid);
  19.         // 获得构建后的原生资源路径（原生资源有图片、音频等，如果不是原生资源将返回空）
  20.         var nativePath = buildResults.getNativeAssetPath(uuid);
  22.         Editor.log(`${prefabUrl} depends on: ${rawPath || nativePath} (${type})`);
  23.     }
  25.     callback();
  26. }
  28. // 修改后
  29. function onBeforeBuildFinish (options, callback) {
  30.     var prefabUrl = 'db://assets/cases/05_scripting/02_prefab/MonsterPrefab.prefab';
  31.     var prefabUuid = Editor.assetdb.urlToUuid(prefabUrl);
  33.     options.bundles.forEach(bundle => {
  34.         // 通过 bundle.buildResults 访问 BuildResults
  35.         var buildResults = bundle.buildResults;
  36.         // 获得指定资源依赖的所有资源
  37.         var depends = buildResults.getDependencies(prefabUuid);
  39.         for (var i = 0; i < depends.length; ++i) {
  40.             var uuid = depends[i];
  41.             // 获得项目中的资源相对 URL（如果是自动图集生成的图片，由于项目中不存在对应资源，将返回空）
  42.             var url = Editor.assetdb.uuidToUrl(uuid);
  43.             // 获取资源类型
  44.             var type = buildResults.getAssetType(uuid);
  45.             // 获得项目中的资源绝对路径（如果是自动图集生成的图片，同样将返回空）
  46.             var rawPath = Editor.assetdb.uuidToFspath(uuid);
  47.             // 获得构建后的原生资源路径（原生资源有图片、音频等，如果不是原生资源将返回空）
  48.             var nativePath = buildResults.getNativeAssetPath(uuid);
  50.             Editor.log(`${prefabUrl} depends on: ${rawPath || nativePath} (${type})`);
  51.         }
  52.     });
  54.     callback();
  55. }

更多 bundle 中的对象，详细请参考 定制项目构建流程。