飞冰项目默认使用 ice-scripts 作为开发工具，ice-scripts 提供了丰富的功能帮助我们提高开发效率：

  • 命令行工具
  • 主题配置
  • 代理配置
  • 自定义 webpack 配置
  • Mock
  • ……

本文会讲述 ice-scripts 完整的使用指南。PS: 请保证 ice-scripts 版本为 1.1.0 及以上。

命令行工具

ice-scripts 提供了 dev/build 的开发命令，如果使用 Iceworks 开发，那么大多数时候你不需要关心这些命令。

ice dev

启动调试服务

  1. $ ice dev --help
  3. Usage: ice-dev [options]
  5. Options:
  6.   -p, --port <port>      服务端口号
  7.   -h, --host <host>      服务主机名
  8.   --https                开启 https
  9.   --analyzer             开启构建分析
  10.   --analyzer-port        设置分析端口号
  11.   --disabled-reload      关闭 hot reload
  12.   --project-type <type>  项目类型, node|web (default: "web")
  13.   --inject-babel <type>  注入 babel 运行环境, Enum: polyfill|runtime (default: "polyfill")

比如使用 3000 端口启动 dev server

  1. $ ice dev -p=3000

比如开启 https

  1. $ ice dev --https

ice build

构建代码

  1. $ ice build --help
  3. Usage: ice-build [options]
  5. Options:
  6.   --debug                debug 模式下不压缩
  7.   --hash                 构建后的资源带 hash 版本
  8.   --project-type <type>  项目类型, node|web (default: "web")
  9.   --inject-babel <type>  注入 babel 运行环境, Enum: polyfill|runtime (default: "polyfill")

主题配置 - themeConfig

ICE 提供了主题功能，以满足业务和品牌多样化的视觉需求，包括但不限于主色、圆角、边框等的视觉自定义配置。

  • Layout 主题配置：由 Layout 提供能力支持，比如可传入 dark 、Light 或者其他自定义的主题（注：需要看模板是否支持 Layout 主题配置）
  • 组件主题配置：由基础组件提供能力支持，通过主题功能可以实现对组件基础样式的个性化配置

需要在 package.json 中新增 themeConfig 字段进行配置，默认的 icedesign 风格由皮肤包 @icedesign/skin 提供，你也可以基于该皮肤包进一步定制:

  1. // in package.json
  3. ...
  5. "buildConfig": {
  6.   "theme": "@icedesign/skin", // 主题包
  7. },
  8. "themeConfig": {
  9.   "theme": "dark",            // layout 主题配置
  10.   "primaryColor": "red",      // 主品牌色
  11.   "secondaryColor": "grey",   // 副品牌色
  12. },
  14. ...

代理配置 - proxyConfig

参考 Iceworks 插件-代理配置

构建配置 - buildConfig

除了提供主题配置和代理配置之外， ice-scripts 还提供了一些常用的构建配置项，方便开发者快速自定义配置，在 package.json 中新增 bulidConfig 字段，包含以下配置项：

配置项

  1. // 配置项遵循 webpack 的配置规则：https://webpack.js.org/configuration/
  2. "buildConfig": {
  3.    "entry": "",             // 指定入口文件
  4.    "output": {},            // 指定输出配置项
  5.    "externals": "",         // 外部扩展配置
  6.    "localization": true     // 资源是否本地化
  7. }

配置示例

如自定义 entry 的配置，默认会以 src/index.js 文件作为入口文件，配置在项目的 package.json 的 buildConfig 字段中；如果你需要改变默认的入口文件，可以自行修改即可生效。

  1. "buildConfig": {
  2.   "entry": "src/index.js"
  3. }

如果你的项目是多页应用，希望把 src/pages 的文件作为入口，那么可以这样配置：

  1. "buildConfig": {
  2.   "entry": [
  3.      "dashboard": 'src/dashboard/index.js',
  4.      "about": 'src/about/index.js'
  5.   ]
  6. }

自定义配置 - .webpackrc.js

ice-scripts 除了提供 buildConfig 用于快速的配置入口之外，也支持自定义配置需求，几乎可完全自定义 webpack 的所有配置项；在项目根目录新建 .webpackrc.js 文件对默认配置进行定制和覆盖。.webpackrc.js 文件需要导出一个函数，其支持的参数可以参考 webpack 官方文档。

正常情况下，我们不推荐使用 .webpackrc.js 的方式自定义配置，因为这可能给项目的长期维护带来负担。如有需求可以先反馈给飞冰团队评估是否可以直接内置到 ice-scripts 或者通过 buildConfig 的方式支持。

.webpackrc.js 文件采用操作系统中安装的 Node.js 所支持的语法，所以可以使用除了 import, export 等之外的几乎所有 ES6 语法。

  1. module.exports = (context) => {
  2.   const { webpack } = context;
  4.   // webpack config
  5.   return {
  6.     plugins: [
  7.       new webpack.DefinePlugin({
  8.         ASSETS_VERSION: '0.0.1',
  9.       }),
  10.     ],
  11.   };
  12. };

以下为一些常见的自定义需求：

修改编译的路径为 dist

  1. const path = require('path');
  3. module.exports = (context) => {
  4.   return {
  5.     output: {
  6.       path: path.resolve('dist'),
  7.     },
  8.   };
  9. };

修改 publicPath

配置 webpack 的 output.publicPath 属性。

  1. module.exports = (context) => {
  2.   return {
  3.     output: {
  4.       path: path.resolve(__dirname, 'public/assets'),
  5.       publicPath: 'https://cdn.example.com/assets/',
  6.     },
  7.   };
  8. };

详细说明

使用 DefinePlugin

官方文档

通过 webpack 的 DefinePlugin 可以配置全局的变量，针对开发环境和发布环境的构建配置不同的行为非常有用。

比如需要在代码里使用当前仓库的版本号：

  1. module.exports = (context) => {
  2.   const { webpack } = context;
  3.   return {
  4.     plugins: [
  5.       new webpack.DefinePlugin({
  6.         // 此处不能省略 JSON.stringify，否则构建过程会出现语法问题
  7.         ASSETS_VERSION: JSON.stringify('0.0.1'),
  8.       }),
  9.     ],
  10.   };
  11. };

在代码里使用该变量（当做全局变量使用）：

  1. console.log(ASSETS_VERSION);

alias

配置 webpack 的 resolve.alias 属性，创建 import 或 require 的别名，来确保模块的引用变得更简单

  1. const path = require('path');
  3. module.exports = () => {
  4.   return {
  5.     //...
  6.     resolve: {
  7.       alias: {
  8.         Utilities: path.resolve(__dirname, 'src/utilities/'),
  9.         Templates: path.resolve(__dirname, 'src/templates/'),
  10.       },
  11.     },
  12.   };
  13. }

现在，替换「在导入时使用相对路径」这种方式，就像这样：

  1. -import Utility from '../../utilities/utility';
  2. +import Utility from 'Utilities';

Mock

ice-scripts 支持 mock 功能，在项目根目录的 mock/index.js 中进行配置，支持基于 require 动态分析的实时刷新，支持 ES6 语法，以及友好的出错提示：

  1. export default {
  2.   // 支持值为 Object 和 Array
  3.   'GET /api/users': { users: [1, 2] },
  5.   // GET POST 可省略
  6.   '/api/users/1': { id: 1 },
  8.   // 支持自定义函数，API 参考 express@4
  9.   'POST /api/users/create': (req, res) => {
  10.     res.end('OK');
  11.   },
  12. };

使用 public 目录

我们约定 public 目录下的文件会在 dev 和 build 时被自动 copy 到输出目录（默认是 ./build）下。所以可以在这里存放
favicon, index.html 等。