项目配置

本文档描述了项目配置的全部参数及使用方法。

配置一览表

项目全局配置

平台内构建配置

平台内构建配置是针对某一端执行命令构建时的特殊配置，可用终端关键词列表

配置文件

chameleon的构建过程是配置化的，项目的根目录下提供一个chameleon.config.js文件，在该文件中可以使用全局对象cml的api去操作配置对象。例如：

// 设置静态资源的线上路径
const publicPath = '//www.static.chameleon.com/static';

// 设置api请求前缀
const apiPrefix = 'https://api.chameleon.com';

// 合并配置
cml.config.merge({
  templateType: 'html',
  projectName: 'Chameleon',
  base: {
    dev: {
      domain1: 'localhost',
      domain2: 'localhost'
    },
    build: {
      domain1: 'http://www.cml1.com',
      domain1: 'http://www.cml2.com',
    }
  },
  web: {
    dev: {
      hot: true,
      console: true
    },
    build: {
      publicPath: `${publicPath}/web`,
      apiPrefix
    }
  }
})

配置api

• cml.config.merge(obj) merge方式修改配置。
• cml.config.assign(obj) assign方式修改配置
• cml.config.get() 获取config配置

配置对象结构

配置对象的第一级为全局配置，例如projectName,全局配置中有各平台内的配置对象，例如web、wx、weex等。其中base对象用于配置各个平台对象的公共部分。

平台对象内部分为各media的配置对象，例如dev、build。

配置详解

下面就详细介绍配置中的功能。

web端页面文件类型

templateType, String 类型。
该字段控制web端构建出的页面文件类型。

• templateType: 'html' 构建出.html文件，纯前端模板
• templateType: 'smarty' 构建出.tpl文件

例如：

cml.config.merge({
  templateType: 'html'
});

web端页面文件名称

projectName, String 类型。

该字段控制web端构建出的模板文件名称，默认是当前项目的根目录文件夹名称。

例如：

cml.config.merge({
  projectName: 'test_cml',
  templateType: 'html'
})

web端构建出 test_cml.html文件

模板语法

templateLang, String 类型。
chameleon的视图层支持两种模板语法，通过在template上的lang属性做区分，如果不写默认是cml语法。
该字段控制init page 和init component 时生成的cml文件的template模板上的lang属性。
例如：

cml.config.merge({
  templateLang: 'cml'
});

支持端配置

platforms, Array[String]类型。 配置当前项目支持的端，该配置决定cml dev和cml build命令启动构建的端，决定cml init命令初始化多态接口和多态组件时只生成相应端代码。 例如：

cml.config.merge({
  platforms: ['web','wx'],
});

cml dev和cml build只启动web和wx端的构建。

关闭某一端构建

devOffPlatform和buildOffPlatform, Array[String] 类型。 当我们执行cml dev 和 cml build 时会自动构建输出所有平台的代码，可以通过这两个字段控制不需要构建的平台，目前支持取值["web","wx","weex"]。 例如：

cml.config.merge({
  devOffPlatform: ['wx'],
  buildOffPlatform: ['wx']
});

语法检查

enableLinter, Boolean 类型。

默认为 true，是否开启chameleon的语法检查，会在命令行提示语法错误。 例如：

cml.config.merge({
  enableLinter: false
})

多态校验控制

check, Object 类型。 chameleon提供了接口多态与组件多态的写法，同时为了保证代码的质量提供了多态校验的方法，可以通过check字段进行校验的控制。

check.enable, Boolean 类型。 控制是否开启多态校验，默认true。

check.enableTypes, Array[String] 类型。 可取值["Object","Array","Nullable"],控制校验中是否可以定义直接定义Object和Array类型，和是否可以定义可为空类型,默认值为[]。 例如：

cml.config.merge({
  check: {
    enable: true,
    enableTypes: ["Object","Array","Nullable"]
  }
});

全局变量校验

enableGlobalCheck, Boolean 类型。
默认是false,(chameleon-tool 0.2.0版本及之后默认为true)，控制是否进行全局变量的检验。

例如：

cml.config.merge({
  enableGlobalCheck: true
});

全局变量校验白名单

globalCheckWhiteList, Array[String|RegExp] 类型。

chameleon内置了全局变量校验的功能 可以设置白名单不校验某些文件。以文件绝对路径进行匹配，可以是正则表达式径，也可以是字符串的endWiths。

例如：

cml.config.merge({
  globalCheckWhiteList: ['jquery.js',/node_modules/]
});

则所有以 jquery.js 结尾的文件以及 正则匹配 /node_modules/ 的不做校验；

dev服务端口

devPort, Number 类型。 dev模式启动的web服务端口，默认是从8000开始寻找空闲端口，避免了启动多个项目时的端口冲突问题。如果想指定端口可以使用该参数进行配置。 例如：

cml.config.merge({
  devPort: 8080
});

配置babel-loader不处理的文件

excludeBablePath, Array[String|RegExp] 类型。

const path = require('path');
cml.config.merge({
  excludeBablePath:[/test-exclude/,path.resolve(__dirname,'./src/excludes')],
})

这个配置的结果会作为webpack模块配置中 Rule.exclude的值；

配置babel-loader处理的文件

babelPath, Array[String|RegExp] 类型。 默认开发者引入的node_modules中的文件不经过babel，如有文件需要babel，设置该参数。

const path = require('path');
cml.config.merge({
  babelPath:[path.resolve(__dirname,'node_modules/test/')],
})

这个配置的结果会作为webpack模块配置中 Rule.include的值；

cmss处理

cmss，Object类型。 仅用于web端。其中包含rem及scale属性，web端构建时默认将cpx转为rem，当不需要时转为rem时，将rem置为false，则scale参数生效，scale为像素缩放倍数，默认为1，会将cpx按照scale的设置进行缩放为px。例如：

cml.config.merge({
  cmss: {
    rem: false,
    scale: 0.5
  }
});

该设置web端cpx不转为rem，而缩小1倍转为px，例如10cpx转为5px。

禁用基础样式

baseStyle， Object类型。 chameleon为了让各端样式统一，默认会在全局插入一些基础样式，如果开发者的跨端不需要这些基础样式，可以通过该参数进行设置。key值为端名称，value为Boolean值，是否插入基础样式。例如：

cml.config.merge({
  baseStyle: {
    web: false,
    wx: false,
    weex: false
  },
});

该设置web、wx、weex端均不插入基础样式。

全局引用npm组件库

cmlComponents, Array[String] 类型。 当我们想把npm组件库中的组件全部自动引入，而不需要单独引入时，可以通过该字段配置npm包名称。例如 cml-ui是我们提供的一个npm组件库，可以进行如下配置：

cml.config.merge({
  cmlComponents: ['cml-ui']
});

npm组件库的package.json中的main字段可以指定路径，否则就会查找npm包中的所有cml文件自动引入，自动引入的组件名称为cml文件名称。

配置子项目

subProject, Array[String|Object]类型。 当配置项为Object时， npmName表示该子项目的地址(从node_modules层级开始配置)， isInjectBaseStyle表示该子项目是否注入基础样式； 当配置项为String时，该值直接表示该子项目的地址(从node_modules层级开始配置)，此时不支持配置是否注入基础样式，子项目默认注入基础样式。例如：

cml.config.merge({
  subProject: [
    {
      npmName: '@didi/cml-login',
      isInjectBaseStyle: false
    },
    '@didi/base-style-test'
  ],
})

项目优化

chameleon-tool@1.0.5-alpha.1 开始支持

cml.config.merge({
  optimize: {
  watchNodeModules: false// 默认不对node_modules中的文件进行watch,提升编译性能
}）

全局样式

chameleon-tool@1.0.5-alpha.1 开始支持

使用参考demo

cml.config.merge({
  globalStyleConfig:{
    //globalCssPath 该路径下的样式对非 weex 端生效；
    globalCssPath:path.join(__dirname,'src/assets/global.config.less'),
    weexCssConfig:{
      //该文件内的样式会作为全局样式导入
      weexCssPath:path.join(__dirname,'src/assets/global.weex.less'),
      //由于weex端本身的限制，假如某些情况下，要覆盖内置组件的某个样式，我们提供了对于该组件注入样式的方式，注入的样式只会对该组件生效
      injectCss:[{
        componentPath:path.join(__dirname,'node_modules/cml-ui/components/c-dialog/c-dialog.cml'),
        cssPath:path.join(__dirname,'src/assets/c-dialog.less')
      }]
    }
  }
})

构建结果信息

buildInfo, Object 类型。 buildInfo.wxAppId,String 类型。微信的appId。

当执行完cml build后会生成一个config.json文件，该文件存储构建后各平台的页面信息。可以通过这个json文件做页面的动态下发，页面降级等等。

例如：

cml.config.merge({
  buildInfo: {
    wxAppId: '123456'
  }
});

cml build 后生成在dist/config.json

    {
        "wx": {
            "appId": "123456",
            "path": "/pages/index/index"
        },
        "web": {
            "url": "https://api.chameleon.com/cml/h5/index"
        },
        "weex": {
            "url": "https://static.chameleon.com/pinche/hkcml/weex/hybridkits_pageone_e86b77ae05a015a3a546.js",
            "query": {
                "path": "/pages/index/index"
            }
        }
    }

config.json中微信小程序的appId是通过buildInfo配置生成，其他的页面信息是根据router.config.json中的配置生成。

例如：

cml.config.merge({
  enableLinter: false
});

构建入口与页面

默认的入口与页面集成在脚手架中，对于有特殊需求的开发者，chameleon提供了可以自定义web端构建入口与页面，weex端构建入口的功能。 entry, Object 类型。 entry.template, String 类型。 页面文件的绝对路径。 entry.web, String 类型。 web端入口文件的绝对路径。 entry.weex, String 类型。 wewx端入口文件的绝对路径。 例如：

var path = require('path');
cml.config.merge({
  entry: {
    template: path.resolve('./src/index.html')
    web: path.resolve('./src/mian.web.js')
    weex: path.resolve('./src/main.weex.js')
  }
})

平台内配置

每一个平台的构建会需要不同的配置，所以针对每一个平台会有一个平台配置对象，平台配置对象中又有多个media配置对象，例如dev或者build的配置。下面讲述的配置项都是放在media对象中。例如： wx web weex是平台对象，里面的dev和build是media对象。

cml.config.merge({
  wx: {
    dev: {},
    build: {}
  },
  web: {
    dev: {},
    build: {}
  },
  weex: {
    dev: {},
    build: {}
  }
});

以下介绍平台内配置支持的配置项

文件指纹

文件指纹是文件的唯一标识，以文件的内容生成hash值作为文件名称的一部分。在开启强缓存的情况下，如果文件的 URL 不发生变化，无法刷新浏览器缓存。文件指纹用于更新浏览器的缓存。小程序端不需要文件指纹。 默认图片资源开启hash，build模式开启hash。通过hash字段配置。

hash, Boolean 类型。 控制打包出的js和css文件是否带hash后缀，图片字体等静态资源自动带hash，其小程序端不支持hash参数。

例如：

cml.config.merge({
  web: {
    dev: {
      hash: true
    }
  }
})

下图为web端开启文件指纹的打包结果。

代码压缩

为了减少资源网络传输的大小，通过压缩器对 js、css、图片进行压缩是一直以来前端工程优化的选择。在chameleon中只需要配置minimize参数。

minimize, Boolean 类型。

控制打包出的文件是否进行压缩。

例如：

cml.config.merge({
  web: {
    dev: {
      minimize: true
    }
  }
});

资源发布路径

publicPath, String 类型。 控制代码中静态资源的引用路径，线上发布需要用到，media为dev时默认 小程序端是本地路径，web和weex端是当前dev服务的路径。 例如：

cml.config.merge({
  web: {
    build: {
      publicPath: "http://www.chameleon.com/static"
    }
  }
});

注：apiPrefix、publicPath、router.config.json、chameleonUrl的关系

热更新与自动刷新

热更新与自动刷新都是提高本地开发效率的手段，当项目中的源代码发生改变时，能够自动的在页面看到改变，其中热更新不需要重新刷新预览的页面。目前只有web端的开发支持热更新，通过hot参数配置。 dev模式默认自动刷新，web端可以选择开启热更新。

hot, Boolean 类型。

控制是否开启热更新，只在web端生效，开启热更新时，css代码不会单独分离出来，如果进行线上js代理本地js调试问题时，请关闭热更新。

例如：

cml.config.merge({
  web: {
    dev: {
      hot: true
    }
  }
});

打包资源分析

analysis, Boolean类型。

控制是否打开webpack打包分析工具， 内部使用的webpack-bundle-analyzer插件。

例如：

cml.config.merge({
  web: {
    dev: {
      analysis: true
    }
  }
});

调试窗口

console, Boolean类型。

控制是否打开页面上的调试窗口，只在web端有效，方便在真机上进行调试。

例如：

cml.config.merge({
  web: {
    dev: {
      console: true
    }
  }
})

内置变量

definePlugin, Object类型，内部使用webpack.DefinePlugin实现，定义运行时的内置变量。 例如：

cml.config.merge({
  web: {
    dev: {
      definePlugin: {
        'process.env.TEST': JSON.stringify('CML_TEST')
      }
    }
  }
})

api请求前缀

apiPrefix, String类型。 这个配置与网络请求相关，在wx和weex项目中，ajax的请求不能像web端一样只写相对路径，而是要写带有域名的绝对路径，chameleon-api 这个基础库，提供了网络请求的api，get、post、request方法，该方法会在运行时将请求的相对路径上添加配置的apiPrefix。media是dev时 默认为当前dev服务的地址,不需要配置。 例如： chameleon.config.js

// 设置api请求前缀
const apiPrefix = 'http://api.chameleon.com';
cml.config.merge({
  wx: {
    dev: {
    },
    build: {
      apiPrefix
    }
  }
})

<script>
import cml from 'chameleon-api'
class Index {
  methods = {
    sendGet() {
      cml.get({
        url: '/api/driver/getList',
        data: {
          name: 'cml',
          age: 18
        }
      }).then(res=>{
        console.log(res)
      }).catch(e=>{
        console.log(e)
      })
    }
  }
};
export default new Index();
</script>

在执行cml wx dev命令构建的结果中，cml.get方法发送的请求是http://172.22.137.29:8000/api/driver/getList

在执行cml wx build命令构建的结果中，cml.get方法发送的请求是http://api.chameleon.com/api/driver/getList

注：apiPrefix、publicPath、router.config.json、chameleonUrl的关系

模块标识类型

moduleIdType,String类型。 设置webpack打包模块的id类型。

• number 顺序排列的数组下标。
• hash 利用 webpack.HashedModuleIdsPlugin() 模块的id类型为模块内容的hash值。
• name 利用webpack.NamedModulesPlugin() 模块的id类型为文件的路径。
• chameleon 用于build模式，模块的id类型为模块内容的hash，并且最终文件的hash也经过优化处理，根据文件内容绝对hash值。 默认media为dev时 取值为name 方便开发调试， media为build时取值为chameleon 保证hash值由文件内容决定，更好的做缓存持久化。

例如：

cml.config.merge({
  web: {
    dev: {
      moduleIdType: "number"
    }
  }
})

babelPolyfill

chameleon-tool@0.0.15 开始支持 web端 chameleon-tool@0.3.0 开始支持 小程序端 chameleon-tool@0.3.3 开始支持 weex端

babelPolyfill, Boolean 类型, 默认 false。 一些es6+的语法，babel不会转义，例如Object.sssign、Object.entries等方法, 如果客户端运行环境不支持这些语法就会出错。其中web使用的是@babel/polyfill, 小程序端使用的是自写的一些方法的polyfill，参见miniappPolyfill,weex端使用的是自写的一些方法的polyfill，参见weexPolyfill。 注意添加polyfill后会增加一些文件体积。

例如：

cml.config.merge({
  base: {
    dev: {
      babelPolyfill: true
    },
    build: {
      babelPolyfill: true
    }
  }
})

domain多域名请求前缀

chameleon-tool@0.2.1 chameleon-api@0.3.1开始支持

domain, Object 类型。 一般配置在base对象中，作为所有平台的公共配置，dev模式中配置的localhost会替换成当前dev模式启动的web服务ip+端口。 具体使用文档参见api多域名mock

例如：

cml.config.merge({
  base: {
    dev: {
      domain: {
        domain1: "localhost",
        domain2: "localhost"
      },
    },
    build: {
      domain: {
        domain1: "http://api.cml.com",
        domain2: "http://api2.cml.com"
      },
    }
  },
})

自定义构建配置

如果我们需要多套构建配置，可以自定义一个media，比如设置weex.custom 对象，然后执行cml weex custom即可使用你设置的custom配置进行构建，但是不会启动dev服务和watch。 例如：

cml.config.merge({
  weex: {
    custom: {
      minimize: true,//对打包结果进行压缩
      moduleIdType: "name" //编译的模块结果以模块名字显示
    }
  }
})

自定义构建配置可配置项和上面介绍的平台内配置项是一样的，比如同样支持 publicPath apiPrefix hash minimize anslysis 等；

假如你在构建微信小程序端，一个构建模式下要求不压缩代码，一个构建模式下要求显示模块名字，那么可以如下配置

cml.config.merge({
  wx: {
    build: {
      minimize: true,//对打包结果进行压缩
      moduleIdType: "id" //编译的模块结果以模块名字显示
    }
    custom: {
      minimize: false,//对打包结果进行压缩
      moduleIdType: "name" //编译的模块结果以模块名字显示
    }
  }
})

执行 cml wx build 则打包的代码会进行压缩以及模块名以id取名； 执行 cml wx custom 则打包的代码不会压缩抑菌剂模块名以该模块对应的name取名

组件导出配置

组件导出相关的配置请参见组件导出介绍。

修改webpack配置

在chameleon.config.js中可以通过api获取到构建之前的webpack配置并对其进行修改。使用方式：

cml.utils.plugin('webpackConfig', function({ type, media, webpackConfig }, cb) {
  // cb函数用于设置修改后的配置
  cb({
    type,
    media,
    webpackConfig
  });
});