apollo-build

apollo-build 是一个构建工具，提供 server、 build、buildDll 和 test 四个命令，分别用于本地调试、构建、打包 dll 和测试，并且提供了特别易用的 mock 功能。命令行体验和 create-react-app 一致，配置略有不同，比如默认开启 css modules，然后还提供了 [JSON 格式的配置方式]。

快速开始

首先，我们会帮您搭建 npm 私有仓库。

安装

# --registry 为 npm 私有仓库的地址 $ npm i apollo-build -g --registry=http://xxx.x.x.x 

使用

本地开发

$ apollo-build server 

打包发布

$ apollo-build build 

打包 dll 静态文件

$ apollo-build buildDll 

测试，默认会跑 ./test 目录下的所有文件

$ apollo-build test 

特性

• HMR (热替换)

CSS 在开发模式下会走 style-loader (被内嵌在 JavaScript 文件中)，所以只要保证 JavaScript 的热更新，即可实现 CSS 的热更新。

如果大家使用 apollo ，配上 babel-plugin-dva-hmr 即可实现 routes 和 components 以及相关 CSS 修改的热更新，其他修改会自动刷新页面。

"env": {   "development": {     "extraBabelPlugins": ["dva-hmr"]   } } 

• Mock

server 支持 mock 功能，默认读取根目录下的.roadhogrc.mock.js文件

比如：

export default {   // 支持值为 Object 和 Array   'GET /api/users': { users: [1,2] },    // GET POST 可省略   '/api/users/1': { id: 1 },    // 支持自定义函数，API 参考 express@4   'POST /api/users/create': (req, res) => { res.end('OK'); },    // Forward 到另一个服务器   'GET /assets/*': 'https://assets.online/',    // Forward 到另一个服务器，并指定子路径   // 请求 /someDir/0.0.50/index.css 会被代理到 https://g.alicdn.com/tb-page/taobao-home, 实际返回 https://g.alicdn.com/tb-page/taobao-home/0.0.50/index.css   'GET /someDir/(.*)': 'https://g.alicdn.com/tb-page/taobao-home', }; 

• 智能重启

配置文件修改的修改会触发 server 的自动重启，会触发重启的文件有：

• .roadhogrc
• .roadhogrc.js
• .roadhogrc.mock.js
• theme 配置指定的文件

配置

关于配置的一些基本概念：

• 配置存于 .roadhogrc 文件中（如果你不喜欢 JSON 配置，可以用 .roadhogrc.js 以 JS 的方式编写，支持 ES6）
• 格式为 JSON，允许注释
• 支持通过 webpack.config.js 以编码的方式进行配置，但不推荐，升级可能会引起兼容问题。使用时会给予警告。（webpack.config.js 本身的编写支持 ES6，会通过 babal-register 做一层转换。）

/**  * webpack.config.js  例子  * @param webpackConfig  webpack配置文件  * @param env process env  * @param webpack  webpack对象，用于部分插件配置  * @param args 命令行参数对象  * @returns {*}  */ module.exports = function (webpackConfig, env, webpack, args) {   //覆盖默认的webpackConfig   return webpackConfig } 

默认配置：

{   "entry": "src/index.js",   "disableCSSModules": false,   "cssModulesExclude": [],   "publicPath": "/",   "outputPath": "./dist",   "extraBabelPlugins": [],   "extraBabelPresets": [],   "extraPostCSSPlugins": [],   "sass": false,   "hash": true,   "autoprefixer": null,   "proxy": null,   "externals": null,   "library": null,   "libraryTarget": "var",   "define": null,   "env": null,   "theme": null,   "templatePath" : null,   "commonChunks": null,   "publicFilePath": "public" } 

entry

指定 webpack 入口文件，支持对象、字符串、 glob 格式以及数组格式

如果你的项目是单入口类型，直接使用字符串定位路径到入口文件即可

如果你的项目是多入口类型，并希望按照模块目录来输出类似src/project1/index.js 和 src/project2/index.js 的文件作为入口。可以这样配：

 "entry": {     "project1/index": "./src/project1/index.js",     "project2/index": "./src/project2/index.js",   }, 

这样的最终build打包的输出会是：

$ apollo-build server 0

• 注意需要结合 templatePath 的多入口配置和对应多入口模板一起使用比较好，否则无法正确自动生成 html 入口文件，需要手工去更新 html 入口文件
• 注意 static 静态资源的引入相对路径会因为多入口打包路径的不同而变化
• 多入口具体使用可以参考下面多入口的使用说明

disableCSSModules

禁用 CSS Modules。最好别关，熟悉并使用他后，你会发现写样式简单了很多。

cssModulesExclude

支持 CSSModules 混用，通过 cssModulesExclude 可指定不需要走 CSSModules 的文件列表。

$ apollo-build server 1

hash

使用 hash 文件名。

$ apollo-build server 2

publicPath

配置生产环境的 publicPath，开发环境下永远为 /。

outputPath

配置输出路径，默认是 ./dist。

publicFilePath

配置 build 和 server 模式下要拷贝到 outputPath 根目录下的文件路径，默认是 public.

extraBabelPlugins

配置额外的 babel plugin。babel plugin 只能添加，不允许覆盖和删除。

比如，同时使用 antd, dva 时，通常需要这么配：

$ apollo-build server 3

同时安装相关依赖：

$ apollo-build server 4

注意：这么配还有个问题，dva-hmr 是开发环境的插件，如果 build 时也用上就会打出冗余代码。解决方案详见 #env。

extraBabelPresets

配置额外的 babel preset

比如：

$ apollo-build server 5

同时安装相关依赖：

$ apollo-build server 6

extraPostCSSPlugins

配置额外的 postcss 插件。

注意：由于 postcss 的插件是以函数的方式进行配置的，所以这个配置只能在 .roadhogrc.js 里使用。

比如：

$ apollo-build server 7

autoprefixer

配置 autoprefixer 参数，详见 autoprefixer 和 browserslist。

比如，如果是做移动端的开发，可以配成：

$ apollo-build server 8

sass

支持 sass，值为 node-sass 的配置参数。

注意：开启 sass 支持需在项目代码中安装 node-sass 和 sass-loader 两个依赖。

因为安装 node-sass 需要下载 github 上面的一些库，因此容易失败，如果失败可以查看下面的链接 node sass 安装失败解决方法

proxy

配置代理，详见 webpack-dev-server#proxy。

如果要代理请求到其他服务器，可以这样配：

$ apollo-build server 9

然后访问 /api/users 就能访问到 http://jsonplaceholder.typicode.com/users 的数据。

如果要做数据 mock，可以考虑和 json-server 结合使用，把 /api 代理到 json-server 启动的端口。

externals

配置 webpack 的 externals 属性。

library

配置 webpack 的 library 属性。

libraryTarget

配置 webpack 的 libraryTarget 属性。

define

配置 webpack 的 DefinePlugin 插件，define 的值会自动做 JSON.stringify 处理。

env

针对特定的环境进行配置。server 的环境变量是 development，build 的环境变量是 production。

比如：

$ apollo-build build 0

这样，开发环境下的 extraBabelPlugins 是 ["transform-runtime", "dva-hmr"]，而生产环境下是 ["transform-runtime"]。

theme

配置主题，实际上是配 less 的 modifyVars。支持 Object 和文件路径两种方式的配置。

比如：

$ apollo-build build 1

或者，

$ apollo-build build 2

svgSpriteLoaderDirs

配置一个路径数组, 该路径下的 svg 文件会全部交给 svg-sprite-loader 处理

$ apollo-build build 3

templatePath 支持输入是字符串或者是对象。 对于普通的单页应用，直接传入字符串指定模板路径即可。 对于多入口应用，需要传入类似下面的对象：

$ apollo-build build 4

参数信息可以参考 html-webpack-template

• 注意多入口应用的 template 一般需要关闭默认的 inject, 需要使用定制化的模板来保证 chunks 可以正确插入，多入口具体使用可以参考下面多入口的使用说明
• 注意 static 静态资源的引入相对路径会因为打包路径的不同而变化

commonChunks

传入数组，用来指定把相应的包和对应依赖抽取成单独的文件。

• name 字符串 代表 chunk名，也对应最后生成的文件名。
• chunks 数组 代表需要抽取的包名

如下配置，会从 appllo 和 react 依赖中生成 stable.[hash:8].js 和 react.[hash:8].js

$ apollo-build build 5

dllPlugin 配置是否需要使用 webpack dll plugin 。默认会把 node_modules 里面的引用库到 node_modules/roadhog-dlls 。可以使用 include 来 包含更多的库，库的引用路径为 app 当前路径以及 node_modules , 使用 exclude 来去掉包含的库。 注意：库的 package.json 里面没有包含有效入口的库以及 css 库无法引入到 dll中，例如下面的例子，exclude 的库是无法编成 dll 的。

$ apollo-build build 6

环境变量

环境变量可配置一些参数，包括：

• PORT，端口号，默认 8000
• HOST，默认 localhost
• HTTPS，是否开启 https，默认关闭
• BROWSER，设为 none 时不自动打开浏览器
• CLEAR_CONSOLE，设为 none 时清屏

比如，使用 3000 端口开启服务器可以这样：

$ apollo-build build 7

命令行参数

apollo-build server

$ apollo-build build 8

apollo-build build

$ apollo-build build 9

apollo-build buildDll

把通用库打成 dll，再使用 apollo-build server 的时候能够减少编译时间，具体详情可以参考 webpack dll plugin

$ apollo-build buildDll 0

apollo-build test

$ apollo-build buildDll 1

使用 public 目录

我们约定默认在 public 目录下的文件会在 server 和 build 时被自动 copy 到输出目录（默认是 ./dist）下。所以可以在这里存放 favicon, iconfont, html, html 里引用的图片等。 注意约定 public/opt 下面的 js类型文件会在 apollo build 的时候被压缩。

FAQ

那么为什么提供 JSON 级别的约定型配置，而非类似 webpack.config.js 的编码型配置?

首先是 JSON 的方式比较简单，true/false 或是一些简单的字符串就可完成配置；另外，JSON 方式能有效控制使用场景，而编程式的非常不可控，roadhog 的一个简单改动都可能导致之前的配置不可用。

报 Unexpected token 错误，类似下面这样

$ apollo-build buildDll 2

把源码放到 src 目录下，因为非 src 目录下的文件不会走 babel 编译。

Windows/Ubuntu 下每次启动后打开新 Tab 比较烦

$ apollo-build buildDll 3

多入口的使用说明

• 多入口核心是需要在 entry 里面使用对象，指定多个入口地址，一般都需要 templatePath 配合来配置， 才能自动化注入正确生成到chunk到不同的入口 html。同时多入口一般有抽取公用 chunk的 需求，这时候可以结合 commonChunk 来进行公共模块的抽取

• 注意 static 静态资源的引入相对路径会因为多入口打包路径的不同而变化
• 多入口 Demo 项目可以参考apollo-build-multi-entry-demo

注意

当前版本的 apollo build 基于webpack^4.29.6

通过webpack.config.js修改webpack配置时，请按照webpack@4的方式配置

在配置 extraBabelPlugins 和 extraBabelPresets 时，使用 Babel@6 版本的 plugin 和 preset

roadhog is not defined 的错误是配置里面配置了dll , 但是没有运行apollo-build buildDll

css 压缩

目前使用OptimizeCssAssetsPlugin来压缩css， 没有使用css-loader和post-css来压缩