Question

插件需要 export 一个函数，函数会接收到两个参数，第一个是 build-scripts 提供的 pluginAPI，第二个是用户传给插件的自定义参数，如下:

module.exports = (pluginAPI, options) => {
  const { 
    context,
    log,
    onHook 
  } = pluginAPI;
};

pluginAPI 主要包含以下几个参数：

context

包含运行时的各种环境信息：

• command 当前运行命令

• commandArgs script 命令执行时接受到的参数

• rootDir 项目根目录

• userConfig 用户在 build.json 中配置的内容

• pkg 项目 package.json 中的内容

onGetWebpackConfig

在工程获取 webpack 时触发，可以用 webpack-chain 形式修改 webpack 配置：

// 场景一：所有 webpack 任务
module.exports = ({onGetConfig, registerTask}) => {
  registerTask('default', webpackConfig);
  
  onGetWebpackConfig((config) => {
    config.entry('xxx');
  });
}
// 场景二：多 webpack 任务
module.exports = ({onGetConfig, registerTask}) => {
  registerTask('web', webpackConfigWeb);
  registerTask('weex', webpackConfigWeex);
  
  onGetWebpackConfig('web'，(config) => {
    config.entry('xxx');
  });
  
  onGetWebpackConfig('weex'，(config) => {
    config.entry('xxx');
  });
}

onHook

用 onHook 监听命令运行时事件，onHook 注册的函数执行完成后才会执行后续操作，可以用于在命令运行中途插入插件想做的操作。

module.exports = ({ onHook }) => {
 onHook('after.start.compile', () => {
   // do something after dev compile
 });
}

log

script 统一的 log 工具，底层使用 npmlog ，便于生成统一格式的 log

registerTask

谨慎使用，注册多 webpack 任务

module.exports = ({ registerTask }) => {
  registerTask('web', webpackConfigWeb);
  registerTask('weex', webpackConfigWeex);
}

registerUserConfig

谨慎使用，注册 build.json 中的顶层配置字段，用于用户字段校验，可以传入单个配置对象或者包含多个配置对象的数组。
生效的声明周期，在registerTask和onGetWebpackConfig之间
配置对象字段如下：

• name (string)
  字段名称，唯一标识，多个插件无法注册相同的字段
  保留字段：plugins

• validation(string|function)
  字段校验，支持string快速校验，string|boolean|number，也可以自定义函数，根据return值判断校验结果

• configWebpack(function)
  字段效果，具体作用到webpack配置上，接收参数：

• config：webpack chain config

• value: build.json中的字段值

• context：与外部context相同，新增字段taskName表现当前正在修改的task

module.exports = ({registerUserConfig}) => {
  registerUserConfig({
    name: 'entry',
    // validation: 'string',
    validation: (value) => {
      return typeof value === 'string'
    },
    configWebpack: (config, value, context) => {
      config.mode(value)
    },
  });
}

registerCliOption

谨慎使用，注册各命令上支持的 cli 参数，比如 npm start --https 来开启 https

module.exports = ({ registerCliOption }) => {
    registerCliOption({
    name: 'https', // 注册的 cli 参数名称，
    commands: ['start'],  // 支持的命令，如果为空默认任何命令都将执行注册方法
    configWebpack: (config, value, context) => {
        // 命令链路上的相关操作
    }
  })
}

注册函数执行周期，在 userConfig 相关注册函数执行之后

setValue

(key: string | number, value: any) => void
用来在context中注册变量，以供插件之间的通信。

// build-plugin-test
module.exports = ({setValue}) => {
  setValue('key', 123);
}

getValue

(key: string | number) => any
用来获取context中注册的变量。

module.exports = ({getValue}) => {
  const value = getValue('key'); // 123
}

插件通信

插件间需要进行通信的场景诉求：
不同插件之间需要知道彼此的存在来确定是否执行相应的逻辑
多个插件共有的配置信息可以抽出来，在某个插件中进行配置
使用setValue和getValue两个API来实现，分别用于数据的存取，详见插件API部分。
谨慎使用，会造成插件之间的依赖。

生命周期

start

生命周期	参数	调用时机
before.start.load	{args: array // 启动参数}	获取webpack配置之前
before.start.run	-	webpack执行之前
after.start.compile	{url: string // serverUrl, stats: WebpackAssets}	编译结束，每次重新编译都会执行
before.start.devServer	{url: string // serverUrl, devServer:  WebpackDevServer}	中间件加载后，webpack dev server启动前
after.start.devServer	{url: string // serverUrl, devServer:  WebpackDevServer}	webpack dev server启动后

build

生命周期	参数	调用时机
before.build.load	{args: array // 启动参数}	获取webpack配置之前
before.build.run	-	webpack执行之前
after.start.compile	{ err: Error, stats: WebpackAssets}	构建结束