脚本编译

Author: Charley

脚本编译配置用于控制 TypeScript 编译行为 以及 发布版本的代码处理方式。

整体分为两部分：

• 脚本编译选项：影响编译阶段的入口、依赖、宏定义等行为
• 发行版本选项：仅在发布构建时生效，用于裁剪、清理和压缩代码

1、脚本编译选项

1.1 宏定义（defines）

defines 用于在编译阶段注入条件变量，从而在不同环境（调试 / 发布）中执行不同的代码逻辑。最常见的用途是区分调试代码与正式代码。

在代码中，可以通过条件判断直接使用这些宏变量，例如：

if (DEBUG) {
    // 调试逻辑
}

配置说明

• 作用：定义编译期变量，用于区分调试环境与发布环境
• 类型：数组
• 结构：每个元素包含以下字段
  • name（名称）：变量名，默认 "DEBUG"
  • debugValue（调试值）：调试模式下的值，默认 "true"
  • releaseValue（发布值）：发布模式下的值，默认 "false"

1.2 外部包（external）

external 用于声明项目依赖的外部模块或 SDK，这些模块在编译和发布时 不会被打包进最终产物，而是保持为外部引用。

该配置通常用于：

• 引入运行环境已提供的库
• 使用 CDN 或宿主环境注入的模块

配置说明

• 作用：指定不参与打包的外部模块
• 类型：字符串数组
• 使用方式：将模块名直接添加到数组中

1.3 包别名（alias）

alias 用于为模块路径设置别名，以简化 import 路径、提升代码可读性，并避免深层相对路径。

该配置通常与 tsconfig.json 中的 paths 配置配合使用。

配置说明

• 作用：为模块路径设置别名
• 类型：数组
• 结构：每个元素包含
  • oldName（旧名称）：原始路径
  • newName（新名称）：替换后的路径

1.4 字符串编码（charset）

charset 用于指定脚本文件的字符编码格式。在大多数项目中，建议使用 utf8 以支持各种国际字符。

配置说明

• 作用：指定脚本文件编码格式
• 类型：字符串
• 可选值："ascii" / "utf8"
• 默认值："utf8"

1.5 编译入口文件（entries）

entries 用于指定 编译阶段的入口文件列表。

这些文件会被编译工具视为编译起点，并在编译时生成对应的导出语句，确保它们能够被正确编译和引用。

entries 适用于 多入口或模块化编译场景。

配置说明

• 作用：指定编译入口文件
• 类型：字符串数组
• 内容：TypeScript 文件路径

使用建议

• 仅添加需要作为独立模块入口的文件
• 避免添加不必要的入口文件，以免增加编译时间和输出体积
• 在模块化项目中，可为每个主要模块配置一个入口文件

1.6 项目启动脚本（mainScript）

mainScript 用于指定 项目运行时的主启动脚本。

它可以替代默认的启动场景，并允许开发者自行控制场景加载前的初始化逻辑以及启动时机。

与 entries 不同，mainScript 会在编译后被引擎 特殊处理，并直接参与 LayaAir 的启动流程。

配置说明

• 作用：指定项目的主启动脚本
• 类型：字符串
• 内容：指向一个 TypeScript 文件（如 Entry.ts）

使用建议

• 始终将 mainScript 设置为 Entry.ts

• 确保文件中包含标准的启动结构

  // 这个脚本必须是一个异步的main函数，不能修改命名
  export async function main() {
      console.log("Hello LayaAir!");
  
      //示例：加载场景并打开场景
      Laya.Scene.open('Scene.ls');
  }
  

• 避免在 main 函数中编写测试代码，保持启动逻辑简洁

• 遵循 LayaAir 引擎的启动流程规范，确保项目稳定运行

需要重点注意的是，启动脚本的执行，只在发布后，或者是预览模式为启动场景（而不是当前场景）时，才会生效。

1.7 entries 与 mainScript 的区别说明

虽然 entries 和 mainScript 都与“入口”有关，但二者的作用层级和使用场景完全不同。

配置形式

• entries：字符串数组，可指定多个编译入口
• mainScript：单个字符串，只能指定一个启动脚本

作用阶段

• entries：作用于 编译阶段，决定哪些文件作为编译入口
• mainScript：作用于 运行阶段，决定项目从哪个脚本开始执行

编译处理方式

• entries：编译工具会为每个入口生成导出语句，确保参与编译
• mainScript：编译工具会对该文件进行特殊处理，并与引擎启动流程集成

与引擎的关系

• entries：仅是编译工具配置，与引擎无直接关系
• mainScript：直接参与 LayaAir 引擎的启动机制

执行机制

• entries：本身不会被自动执行，需要通过模块引用触发
• mainScript：会在项目启动时由引擎自动加载并执行其 main 函数

2、发布版本选项

发布版本选项仅在 发布构建 时生效，用于控制代码裁剪、调试信息清理以及压缩行为。

2.1 保留未使用的组件脚本（keepUnusedComponentScripts）

默认值为 false。

当启用该选项时，即使某些组件脚本未在场景中被引用，也会被包含在发布版本中。

适用于需要通过代码动态加载组件的场景。

2.2 删除 debugger 语句（dropDebugger）

默认值为 false。

启用后，发布版本中所有 debugger 语句都会被移除。

2.3 删除 console 语句（dropConsole）

默认值为 false。

启用后，发布版本中的 console.log、console.warn 等控制台输出语句将被删除，有助于减少无关输出并优化体积。

2.4 压缩（minify）

用于控制发布版本的代码压缩行为。

2.4.1 保留类和函数名称（keepNames）

默认值为 false。

启用后，压缩后的代码将保留类名和函数名，便于调试堆栈信息，但会略微增加体积。

2.4.2 保留未使用的代码（keepUnused）

默认值为 false。

启用后，即使某些函数或变量在代码中未被使用，也会被保留在压缩后的代码中。