配置文件的详细说明

  本章将带您了解 swpp 的配置文件的组成，以及对 swpp 内置的所有配置项的解释说明。

环境

  无论您是使用 js 还是 ts 编写配置文件，配置文件都将与主体程序共享同一个运行环境，也就是说配置文件中的代码可以访问到主体程序提供的 globalThis 等全局数据。

  简单来说就是 swpp 会使用类似于 require('xxx/xxx/xxx') 的方式加载配置文件，所以相当于您在当前的项目中又编写了一个代码文件。

  知道了这个，就可以在配置文件中进行一些“骚操作”，即可以动态地修改环境中的一些内容。但是 swpp 并不建议这么做，配置文件在设计上用于修改、调整 swpp 的一些行为，如果您确实需要运行一段有副作用的代码，建议优先通过其它更合理的办法进行。

  swpp 会在加载配置时执行配置文件中的代码，如果您在配置文件顶层抛出了异常，那么将会导致配置加载失败，具体会产生什么后果视前端的具体实现而不同，可能会使整个程序直接结束，也可能只终止 swpp 的任务。

  因为配置文件共享主程序的 package.json，所以配置文件中可以使用所有主程序中安装的依赖（包括 swpp 本身）。

修改配置的方法

  swpp 中统一使用 defineXxx 函数定义配置，其中 defineConfig 用于一次性定义所有配置，其余 defineXxx 用于定义某一个分类下的配置。

  非常需要注意的是，配置文件中必须在加载完毕前调用 define 系列函数，否则将会导致错误，所以在异步任务中调用 define 是非常危险的操作。对于 js/ts 功底不好的同学来说，您只需要记住 define 系列的函数必须在顶层调用即可（可以嵌套在 if 等语句中）。

import {defineConfig} from 'swpp-backends'
 
defineConfig({
 
    compilationEnv: {},
    crossEnv: {},
    runtimeDep: {},
    crossDep: {},
    runtimeCore: {},
    runtimeEvent: {},
    domConfig: {},
    compilationFileParser: {},
    modifier: {}
 
})

  注意：上面的示例中一次性列出了所有的分类，实际使用时，建议只写出需要修改的配置，以保持配置文件的简洁性。

配置分类与命名规则

  从上面的示例代码中可以看到，swpp 将内置的配置项分为了八类，其命名规则如下：

• compilation 开头表示该分类下的配置仅在构建时产生影响，不会被写入到 sw 文件中。
• runtime 开头表示该分类下的配置仅会被写入到 sw 文件中，不会在构建时被使用。
• cross 开头表示该分类下的配置在构建时有可能被使用，同时会被写入到 sw 文件中。
• dom 开头表示该分类下的配置会影响 DOM 端 js 的生成。
• modifier 是一项非常特殊且功能强大的配置，后面将会专门进行讲解。

运行顺序

  swpp 会按照如下顺序装配配置：

1. 按优先级将配置文件加载到内存（优先级越高越先加载）
2. 调用 modifier#build 函数构建各个 KV 库（没有 build 则将使用默认实现）
3. 调用 modifier#registry 函数（优先级越低越先执行）
4. 依次将 runtime compilation 和 cross 的配置写入到 KV 库当中
5. 调用 modifier#dynamicUpdate 函数
6. 冻结所有 KV 库

配置优先级

  不同配置文件的优先级依据前端的实现不同而不同，同一个配置文件中越早调用的 define 函数优先级越高。