扩展构建流程

    1. 在编辑器的菜单栏中点击 项目 -> 新建构建扩展包，选择 全局/项目 后即可创建一个构建扩展插件包。

      • 若选择 全局，则是将构建扩展包应用到所有的 Cocos Creator 项目，全局 路径为：

        • Windows：%USERPROFILE%\.CocosCreator\extensions

        • macOS：$HOME/.CocosCreator/extensions

      • 若选择 项目，则是将构建扩展包应用到指定的 Cocos Creator 项目，项目 路径为：

        • $你的项目地址/extensions

    2. 构建扩展包创建完成后会在 控制台 输出生成路径，点击路径即可在操作系统的文件管理器中打开构建扩展包。

    3. 启用构建扩展插件之前需要先在目录下执行 npm install 安装一些依赖的 @types 模块才能正常编译。编辑器自带的接口定义已经生成在编辑器根目录的 resources\3d\engine\@types 文件夹下了，后续通过编辑器主菜单的 开发者 -> 导出 .d.ts 即可获取到最新的接口定义。

    4. 点击编辑器主菜单中的 扩展 -> 扩展管理器，打开 扩展管理器 面板。然后在 扩展管理器 中选择 项目/全局 选项卡，即可看到刚刚添加的构建扩展插件。然后点击右上方的 启用 按钮，即可正常运行插件。

      enable-plugin

    5. 启用构建扩展插件后，打开 构建发布 面板，可以看到构建扩展插件的展开栏。点击 构建 即可加入构建流程。

    6. 如果需要修改构建扩展插件的内容，直接修改 extensions 目录下的构建扩展包即可，具体内容请参考构建扩展包目录下的 readme.md 文件。然后在 扩展管理器 中找到对应的构建扩展插件，点击 重新载入 图标按钮，编辑器中的构建扩展插件便会使用最新的代码和文件重新运行。

      reload

    构建扩展包需要在 package.json 的 contributions 中添加 builder 字段，然后在 builder 字段中指定一个 JavaScript 脚本的 相对路径，作为构建扩展插件参与到构建流程的入口脚本。

    关于入口脚本的配置，代码示例如下：

    1. // builder.ts
    3. export const configs: IConfigs = {
    4.     'web-mobile': {
    5.         hooks: './hooks',
    6.         options: {
    7.             remoteAddress: {
    8.                 label: 'i18n:xxx',
    9.                 render: {
    10.                     ui: 'ui-input',
    11.                         placeholder: 'Enter remote address...',
    12.                     },
    13.                 },
    14.                 // 校验规则，目前内置了几种常用的校验规则，需要自定义的规则可以在 "verifyRuleMap" 字段中配置
    15.                 verifyRules: ['require', 'http'],
    16.             },
    17.             enterCocos: {
    19.                     description: 'i18n:cocos-build-template.options.enterCocos',
    20.                     default: '',
    21.                     render: {
    22.                         // 请点击编辑器菜单栏中的“开发者 -> UI 组件”，查看所有支持的 UI 组件列表。
    23.                         ui: 'ui-input',
    24.                         attributes: {
    25.                             placeholder: 'i18n:cocos-build-template.options.enterCocos',
    26.                         },
    27.                     },
    28.                     verifyRules: ['ruleTest']
    29.                 }
    30.             },
    31.             verifyRuleMap: {
    32.                 ruleTest: {
    33.                     message: 'i18n:cocos-build-template.ruleTest_msg',
    34.                     func(val, option) {
    35.                         if (val === 'cocos') {
    36.                             return true;
    37.                         }
    38.                         return false;
    39.                     }
    40.                 }
    41.             }
    42. };

    在编写入口脚本时还需要额外注意以下几点：

    1. 不同进程中的环境变量会有所差异。入口脚本会同时被 渲染进程 和 主进程 加载，所以请不要在入口脚本中使用仅存在于单一进程中的编辑器接口。进程相关详情请参考下文 调试构建扩展插件 部分的内容。

    2. config 的 key 有两种配置方式：

      • 针对 单个平台 的配置，key 值填写为 平台构建插件名，参考上面的代码示例。各平台对应的构建插件名可在编辑器主菜单的 扩展 -> 扩展管理器 -> 内置 中查看。

      • 针对 所有平台 的配置，key 值填写为 *，参考通过编辑器菜单栏的 新建构建扩展包 生成的 source/builder.ts 文件。

    入口脚本接口定义

    关于入口脚本详细的接口定义，说明如下：

    其中 的接口定义需要参考 。

    在入口脚本的 hooks 字段中定义的脚本，可用于编写构建生命周期的钩子函数。所有的钩子函数都是在构建进程中按照顺序依次执行，不同的钩子函数接收到的数据会有所差异。在构建进程中可以直接使用引擎提供的 API 和 Editor 全局变量，关于 Editor 详细的接口定义请点击编辑器主菜单的 开发者 —> 导出 .d.ts 获取和查看。关于构建进程的说明请参考下文 构建进程 部分的内容。

    公开的钩子函数与构建的生命周期的关系请参考下图：

    钩子函数大致的接口定义如下所示：

    1. declare interface IHook {
    2.     throwError?: boolean; // 插件注入的钩子函数，表示在执行失败时是否直接退出构建流程，并显示构建失败
    3.     // ------------------ 钩子函数 --------------------------
    4.     onBeforeBuild?: IBaseHooks;
    5.     onBeforeCompressSettings?: IBaseHooks;
    6.     onAfterCompressSettings?: IBaseHooks;
    7.     onAfterBuild?: IBaseHooks;
    9.     // 编译生成的钩子函数（仅在构建有“生成”步骤的平台时才有效）
    10.     onBeforeMake?: (root: string, options: IBuildTaskOptions) => void | Promise<void>;
    11.     onAfterMake?: (root: string, options: IBuildTaskOptions) => void | Promise<void>;
    12. }
    13. type IBaseHooks = (options: IBuildTaskOptions, result?: IBuildResult) => void | Promise<void>;

    构建扩展插件参与到构建流程时，相关代码会运行在以下三种进程：

    • 主进程：执行入口脚本及其依赖资源
    • 渲染进程：执行入口脚本中注册到 构建发布 面板上的部分字段
    • 构建进程：执行入口脚本中 hooks 字段定义的脚本

    主进程（入口脚本）

    主进程主要执行构建扩展插件中用于参与构建流程的入口脚本（builder 字段中指定的脚本），以及插件自身的入口脚本（main 字段中指定的脚本）。

    当修改了运行在主进程中的代码时，必须要重启插件，然后再刷新需要更新的进程（这一点会在之后优化，尽量通过一次重启便解决代码更新问题，但刷新依旧是最彻底的重载方法）。主进程目前没有比较合适的调试方法，可以使用命令行打开编辑器查看主进程代码日志来辅助调试：

    1. // Mac
    2. /Applications/CocosCreator/Creator/3.0.0/CocosCreator.app/Contents/MacOS/CocosCreator --project projectPath
    4. // Windows
    5. ...\CocosCreator.exe --project projectPath

    构建扩展插件的入口脚本中，有部分字段是注册到 构建发布 面板上的，例如 options 的显示配置、panel 字段，以及 panel 脚本本身，这部分内容会在渲染进程载入执行。渲染进程其实就是窗口自己的执行进程，打开调试工具，可以调试 构建发布 面板上的 dom 元素、样式、脚本等。

    如果是修改了注册到 构建发布 面板上的代码时，只需要刷新面板即可，无需重启插件。

    • 打开构建发布面板渲染进程的调试工具

      点击 构建发布 面板，然后按下快捷键 Ctrl + Shift + i（Windows）或者 Cmd + Option + i（Mac），即可打开 构建发布 面板的调试工具。

    • 重新载入（刷新）面板方式

      点击 构建发布 面板或者 构建发布 面板的调试工具后，按下 Ctrl/Cmd + R 即可。

    构建进程（hooks 脚本）

    构建的实际执行阶段是单独的一个 worker 进程，确保即使发生异常崩溃也不会影响到其他窗口的正常使用。在入口脚本的 字段中定义的脚本也是在这个单独的 worker 进程中载入执行的。

    如果仅修改 hook 字段定义的脚本，刷新构建进程即可，无需重启插件。刷新方式同上文的 构建发布 面板一致，打开构建调试工具后，按下快捷键 Ctrl/Cmd + R 即可。

    打开构建进程的调试工具

    包括以下三种方式：

    1. 在 构建发布 面板点击构建任务窗口右上方的 打开构建调试工具 按钮。

      dev_tools

    2. 可以在这个消息方法的基础上，根据自己的需要进行扩展。例如：可以在自己编写的构建插件的代码中捕获错误，一旦有异常就自动打开调试工具之类的。