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打包的输出会是：

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

disableCSSModules

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

cssModulesExclude

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

"cssModulesExclude": [
  './src/a.css',
  './src/b.less',
]

hash

使用 hash 文件名。

"hash": true

publicPath

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

outputPath

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

publicFilePath

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

extraBabelPlugins

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

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

"extraBabelPlugins": [
  "transform-runtime",
  "dva-hmr",
  ["import", { "libraryName": "antd", "libraryDirectory": "lib", "style": "css" }]
]

同时安装相关依赖：

$ npm i babel-plugin-transform-runtime babel-plugin-import babel-plugin-dva-hmr --save-dev
$ npm i babel-runtime --save

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

extraBabelPresets

配置额外的 babel preset

比如：

"extraBabelPresets": ["stage-1"]

同时安装相关依赖：

$ npm i babel-preset-stage-1 --save-dev

extraPostCSSPlugins

配置额外的 postcss 插件。

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

比如：

extraPostCSSPlugins: [
  pxtorem({
    rootValue: 100,
    propWhiteList: [],
  }),
],

autoprefixer

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

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

"autoprefixer": {
  "overrideBrowserslist": [
    "iOS >= 8", "Android >= 4"
  ]
}

sass

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

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

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

proxy

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

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

"proxy": {
  "/api": {
    "target": "http://jsonplaceholder.typicode.com/",
    "changeOrigin": true,
    "pathRewrite": { "^/api" : "" }
  }
}

然后访问 /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。

比如：

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

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

theme

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

比如：

"theme": {
  "@primary-color": "#1DA57A"
}

或者，

"theme": "./node_modules/abc/theme-config.js"

svgSpriteLoaderDirs

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

// npm i antd-mobile -S
const path = require('path');
const svgSpriteDirs = [
  require.resolve('antd-mobile').replace(/warn\.js$/, ''), // antd-mobile 内置svg
  path.resolve(__dirname, 'src/my-project-svg-foler'),  // 业务代码本地私有 svg 存放目录
];

export default {
  // ...
  svgSpriteLoaderDirs: svgSpriteDirs,
  //...
}

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

"templatePath": [{
  template: "src/project1/index.ejs",
  filename: 'project1/index.htm',
  inject: false,
  chunks: ['project1/index'],
},
{
  template: "src/project2/index.ejs",
  filename: 'project2/index.htm',
  inject: false,
  chunks: ['project2/index'],
}],

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

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

commonChunks

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

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

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

 "commonChunks": [{
    "name": "stable",
    "chunks": ["apollo"]
  }, {
    "name" : "react",
    "chunks": ["react"]
  }]

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

"dllPlugin": {
  include:[],
  exclude:['babel-runtime','apollo-component-mobile','normalize.css']
},

环境变量

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

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

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

// OS X, Linux
$ PORT=3000 apollo-build server

// Windows (cmd.exe)
$ set PORT=3000&&apollo-build server

命令行参数

apollo-build server

$ apollo-build server -h
Usage: apollo-build server [options]

Options:
  -h      显示帮助      [boolean]
  --ie8   支持 IE8      [boolean] [default: false]

apollo-build build

$ apollo-build build -h
Usage: apollo-build build [options]

Options:
  --debug            不压缩构建                        [boolean] [default: false]
  --watch, -w        监听文件变化并重构建               [boolean] [default: false]
  --output-path, -o  指定输出路径                      [string] [default: null]
  --analyze          可视化分析 webpack bundle         [boolean] [default: false]
  --ie8              支持 IE8                          [boolean] [default: false]
  --sourcemap        构建时生成 sourcemap              [boolean] [default: false]
  --dropconsole      构建时移除 console 日志            [boolean] [default: false]
  -h                 显示帮助                          [boolean]

apollo-build buildDll

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

$ apollo-build buildDll -h
Usage: apollo-build buildDll [options]

Options:
  -h      显示帮助                                      [boolean]

apollo-build test

$ apollo-build test -h
Usage: apollo-build test [options] [mocha-options]

Options:
  --coverage  输出覆盖率                                 [boolean] [default: false]
  -h          显示帮助                                   [boolean]

使用 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 错误，类似下面这样

Error in ./index.js
Module parse failed: /Users/chencheng/Documents/Work/Misc/dva-cli/boilerplates/demo/index.js Unexpected token (15:23)
You may need an appropriate loader to handle this file type.
SyntaxError: Unexpected token (15:23)
 @ multi index

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

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

# Ubuntu
$ BROWSER=none apollo-build server

# Windows
$ set BROWSER=none&&apollo-build server

多入口的使用说明

  • 多入口核心是需要在 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来压缩

Copyright © 民生科技有限公司 2019 all right reserved，powered by Gitbook联系方式: wanglihang@mskj.com
修订时间： 2019-08-02 16:19:32

results matching ""

    No results matching ""