# 配置详解

a8k 封装了大多数 webpack 的配置,将常用的优化配置集成,并且针对 react 技术栈项目做了正对性配置,虽然屏蔽的大多数复杂性,但是为了对不同项目提供一些灵活的配置,a8k 也提供了一些简答且必要的配置项。

基于 a8k 的项目,在根目录下会有一个 a8k.config.js 的配置文件,用于项目的自定义配置

# 基本配置项

# mode

mode 用于指定项目是多页面还是单页面,支持两个值:

描述
single 单页面应用,默认继承 react-router 支持路由,切构建的页面都通过动态导入的方式加载页面 js
multi 多页面应用,每个页面都有自己的入口文件,a8k 会自动抽离公共的代码,在不同的页面间共享

# dist

配置构建生产包(即执行k build)的结果输出目录,默认值:.a8k/static

# publicPath

和 webpack 的 output.publicPath 意义一致,指定在浏览器中所引用的「此输出目录对应的公开 URL」。相对 URL(relative URL) 会被相对于 HTML 页面(或

标签)解析。相对于服务的 URL(Server-relative URL),相对于协议的 URL(protocol-relative URL) 或绝对 URL(absolute URL) 也可是可能用到的,或者有时必须用到,

例如:当将资源托管到 CDN 时

module.exports = {
  //...
  publicPath: 'https://cdn.example.com/assets/',
};

# cacheDirectory

配置构建阶段的缓存目录,默认:.a8k/.cache

a8k 默认会缓存构建中 js、css、html、eslint 的结果,只有当这些文件发生变化时才会重新构建,否则其中所有的 webpack loader 都将从缓存中获取结果,目的是为了提高构建性能

# cssModules

类型boolean or Object,默认值:false,当设置为 true,将自动启用 css modules 能力 参考文档css-loader

# babel

用于指定 babel 需要处理的额外文件或者需要忽略的文件,这在你调试某些库(需要被编译的代码)时非常用,支持两个配置:

include:需要处理的文件

exclude:不需要处理的文件

include、exclude 的处理规则和 webpack rule conditions 的规则一致,详情见webpack rules

使用方法:

module.exports = {
  //...
  babel: {
    include: [/node_modules\/lodash/], //编译lodash
    exclude: [/.*\.min\.js/], //不处理压缩文件
  },
  //...
};

当然你可以直接在项目目录下面使用 babel 官方配置文件,自定义 babel 配置

# crossOrigin

配置通过 script、link 引用的 js、css 资源是否支持跨域。默认false,支持两个值:truefalse

配置为true会在所有的 script 标签上加上crossorigin="anonymous",这对于那些将静态资源部署到 CDN 上的应用非常有用,可以让错误捕获程序捕获到来自 CDN 的 js 错误堆栈。如果资源跨域了,但是没配置这个,当出现未捕获的错误时你只会得到Script Error错误,这对于处理现网问题非常不利。

# devServer

该顶配置项用于指定开发服务器信息,用于修改 webpack-dev-server插件的配置,通常你只需要修改端口信息即可。具体支持的配置项见文档

# 高级配置项

# retry

JavaScript、css 加载多域名重试配置,配置项支持:retryPublicPath,exclude

配置示例:

module.exports = {
  retry: {
    retry: {
      retryPublicPath: '//fudao.qq.com/pc/', //重试的地址前缀
      exclude: [/\/\/sqimg\.qq\.com/, /pub\.idqqimg\.com/], // 通过正则表达式,排除不需要重试的文件
    },
  },
};

# ssrConfig

类型boolean or Object, 默认值false

服务器渲染配置,将支持所有页面,如果需要单独配置部分页面直出,请添加 entry 指定需要直出的页面入口文件

entryPath:服务器渲染代码入口构建存放目录, 默认值:./.a8k/server/entry,不建议修改

viewPath:视图代码存放目录(及 html 模板存放目录), 默认值:./.a8k/server/view,不建议修改

entry:如果你不希望所有页面支持服务器渲染,可以选择自定义支持服务器渲染的页面入口文件

port: required 指定 node 服务启动端口,在开发阶段调试需要代理到该页面

配置示例:

module.exports = {
  //省略其他配置
  ssrConfig: {
    port: 3000, // 配置node服务端口
    entry: ['search'],
  },
};

# ignorePages

正则表达式,配置src/pages目录下面需要排除的文件夹,使用场景是你希望构建不要处理 src/pages 目录下面的某些目录(及排除这些目录作为页面处理)

# escheck 检测构建结果是否支持 es5 浏览器

类型:boolean|{exclude:[],ecmaVersion:string},

a8k 编译的结果 JavaScript 代码支持 es5 及以上浏览器运行。但默认情况不会对 node_modules 模块进行代码转换,你可能会意外的引用了第三方模块(没有提供 es5 版本)。为了避免这种意外的 bug 出现,我们提供了默认的构建结果的 es5 检测,如果发现结果中存在非 es5 的代码,将直接报错。

但是,部分文件是可以允许使用高于 es5 版本的 JavaScript 代码的,例如:service worker 脚本,因为支持 service worker 的浏览器对很多 es6 的语法是支持的。

因此,我们提供了额外的配置允许你排除部分文件,配置方式如下:

在 a8k 配置文件中添加如下代码:

module.exports = {
  // ...
  escheck: {
    exclude: ['you-file'], //支持glob匹配规则
  },
};

# 自定义 webpack 配置

利用了 webpack-chain 实现自定义配置,具体配置项是chainWebpack,该配置项提供一个函数,参数有config、options

config: 是 WebpackChain 实例对象;

options: 中包括了两个重要参数:typemode,其中 type 取值serverclient分别标识服务器代码、前端代码,mode 取值productiondevelopment,标识是生产模式还是开发模式

配置示例:

module.exports = {
  //省略其他配置
  /**
   * @param WebpackChain config webpackChain实例对象
   * @param {type:string,mode:string} options 包括:type取值:server、client;mode取值:production、development
   */
  chainWebpack(config, options) {
    //添加自定义loader
    config.module
      .rule('css')
      .test(/\.(scss|css)$/)
      .use('loader-name') //配置一个名字,方便标识
      .loader('style-loader');
    //自定义plugin
    const Plugin = require('you-plugin-module');
    Plugin.__expression = `require('you-plugin-module')`;
    config.plugin('you-plugin-name').use(Plugin, [params1, params2]);
  },
};

更多配置方法请参考哦webpack chain 文档

# HTML 模板引擎

本项目采用 nunjucks 作为 HTML 的模板引擎,具体使用文档参考nunjucks 文档

上次更新: 8/11/2019, 9:25:45 AM