heirloom-static-plugin v2.0.9
heirloom-static-plugin 
基于Plugin接口，对
koa-static、
koa-compress
以及
koa-webpack-dev-middleware、
koa-webpack-hot-middleware的封装实现。
文档
使用
新建工程：
mkdir example && cd example && npm init配合heirloom-core项目使用
安装依赖：
SASS_BINARY_SITE=https://npm.taobao.org/mirrors/node-sass/ npm install heirloom-core heirloom-static-plugin --save编写example/index.js:
const heirloomServer = require("heirloom-core");
const heirloomStatic = require("heirloom-static-plugin");
const server = new heirloomServer.NormalServer({
logger: console,
port: 4000,
engine: heirloomServer.KoaEngine.shareInstance(),
});
if (process.env.NODE_ENV === 'development') {
// Watch + 热更新
server.apply(new heirloomStatic.StaticDevPlugin({
root: __dirname,
source: "public",
config: "public/config",
publicPath: "/app",
define: { API_ROOT : "http://domain.com" },
}));
} else {
// 启动时构建 + Gzip
server.apply(new heirloomStatic.StaticPlugin({
root: __dirname, // 选填，缺省（默认）：process.cwd()
source: "public", // 选填，静态资源探测目录，缺省（默认）：join(process.cwd(), 'public')
target: "dist", // 选填，构建生成目标目录，缺省（默认）：join(process.cwd(), 'dist')
publicPath: "/app", // 选填，指定静态资源路径到：http://localhost:4000/app，缺省（默认）：／
config: "public/config", // 选填，指定前端环境变量目录
oss: "aliyun", // 选填，"none" - 不上传OSS， "aliyun" - 上传至阿里云OSS，缺省（默认）：none
aliyun: { // oss === 'aliyun'时，必填
domain: 'https://domain.com',
region: 'oss-cn-hangzhou',
accessKeyId: '***',
accessKeySecret: '***',
bucket: 'your-bucket',
},
define: { API_ROOT : "http://domain.com", FOO: 'foo' }, // 选填，定义静态资源JS中全局变量API_ROOT和FOO的值
}));
}
// open http://localhost:4000/app/sample
server.start();编写浏览器端静态资源example/public/sample/index.js:
document.writeln("<h1>Hello World!</h1>");编写浏览器端静态资源example/public/sample/package.json:
{
"name": "sample",
"title": "演示"
"description": "这是一个示例",
"keywords": [
"heirloom",
"static sample"
],
"main": "index.js"
}作为命令行工具单独使用
在example/根目录下执行：
heirloom可以创建example/heirloom.config.js文件，导出StaticPlugin的构造参数，供heirloom采集使用：
// heirloom.config.js
module.exports = {
root: __dirname, // 选填，缺省（默认）：process.cwd()
source: "public", // 选填，静态资源探测目录，缺省（默认）：join(process.cwd(), 'public')
target: "dist", // 选填，构建生成目标目录，缺省（默认）：join(process.cwd(), 'dist')
publicPath: "/app", // 选填，指定静态资源路径到：http://localhost:4000/app，缺省（默认）：／
config: "public/config", // 选填，指定前端环境变量目录
oss: "aliyun", // 选填，"none" - 不上传OSS， "aliyun" - 上传至阿里云OSS，缺省（默认）：none
aliyun: { // oss === 'aliyun'时，必填
domain: 'https://domain.com',
region: 'oss-cn-hangzhou',
accessKeyId: '***',
accessKeySecret: '***',
bucket: 'your-bucket',
},
define: { API_ROOT : "http://domain.com", FOO: 'foo' }, // 选填，定义静态资源JS中全局变量API_ROOT和FOO的值
};package.json配置约定
一个目录如果包含package.json文件将会被加入到构建流程中，
反之，将作为静态资源被拷贝至目标目录下。
示例：
{
"name": "sample",
"title": "演示"
"description": "这是一个示例",
"keywords": [
"heirloom",
"static sample"
],
"main": "index.js",
"homepage": "index.ejs",
"mobile": true,
"growing": {
"accountId": ""
},
"bughd": {
"key": ""
}
}name：路由，缺省，为该目录文件夹名。homepage：首页（index.html）模板文件。缺省，采用默认的HTML模板。main：入口文件。缺省，为index.js。如果入口文件不存在则中断构建。
以下属性，在homepage未设置时有效：
growing: growing.io 配置bughd: bughd 配置mobile: true-移动端高清、多屏适配方案
静态资源自动检测
通过构造参数source，标明静态资源所处的目录。
StaticPlugin会探测source目录及其所有子目录，递归采集所有包含package.json文件目录，从package.json中获取构建所需的信息。
package.json的name和main即webpack配置参数中：entry属性的key和value。
配置前端环境变量
通过构造参数config，标明前端环境变量的目录。
构建前端资源时，可通过指定node.js的环境变量NODE_ENV和config目录下的对应文件名来指定前端环境变量。如果配置config，没有创建相对应的confg文件，则会报错。NODE_ENV默认值为develpment。
示例：
构造参数config值为public/config, NODE_ENV的值为develpment和production。则以下目录和文件应存在：
public/
├── config/
│ ├── develpment.js-----------------------包含development环境下的变量
│ ├── production.js--------------------------包含development环境下的变量develpment.js的内容可为：
export const API_ROOT = 'https://development.xuyuanxiang.me';其它前端文件使用：
import { API_ROOT } from 'Config';注意：使用eslint进行语法检查时，会对上面的引用报错找不到相应的包，可用// eslint-disable-next-line注释。
环境变量
webpack.EnvironmentPlugin默认从process.env中采集：NODE_ENV环境变量。
额外的环境变量或全局变量可通过新增的构造参数：define传入：
服务器端初始化StaticPlugin（或StaticDevPlugin）时，传入define参数：
new StaticPlugin({
...,
define: { API_ROOT : "http://domain.com", FOO : process.env.FOO },
})在浏览器端文件中，可获取全局变量：API_ROOT及FOO
const response = fetch(`${API_ROOT}/api/v1/foo?foo=%{FOO}`)；
// 读取 NODE_ENV：
console.log(process.env.NODE_ENV);自定义webpack配置参数
使用方法：
在工程根目录下存放webpack.config.js文件，StaticPlugin会将该文件配置信息以最高优先级使用覆盖到默认配置中。
注意：目前自定义的webpack.config.js文件中，只支持requireNode核心模块及node_modules下的自定义模块。不支持路径形式的模块。
关于样式
但推荐使用sass.
已知问题：使用CSS Modules时，less-loader无法将.less中url()方法指向的图片正确加入到webpack构建流程。
postcss-import
heirloom-static-plugin支持向如下方式引入你的项目中安装的依赖：
@import "normalize.css"; /* 等价于 @import "./node_modules/normalize.css/normalize.css"; */Babel
默认.babelrc文件
这是目前heirloom-static-plugin构建所采用的.babelrc配置:
const browsers = [
'Android 2.3',
'Android >= 4',
'Chrome >= 35',
'Firefox >= 31',
'Explorer >= 9',
'iOS >= 7',
'Opera >= 12',
'Safari >= 7.1',
];
const babelPlugins = [
'syntax-dynamic-import',
];
if (process.env.NODE_ENV === 'production') {
babelPlugins.push('transform-remove-console', 'transform-react-remove-prop-types');
}
ignore: 'node_modules',
presets: [
[
'env',
{
useBuiltIns: true,
targets: { browsers },
},
],
'flow',
'es2017',
'react',
'stage-1',
],
plugins: babelPlugins,如果你的工程根目录下存在.babelrc会覆盖以上配置。
关于Polyfill
不建议使用babel-runtime + babel-plugin-transform-runtime。我曾有过在Android 4.x.x版本中报缺少Array.includes方法错误的经历。
可以在你的入口文件中引入：
import "babel-polyfill";babel-preset-env会根据targets.browsers中所指定的目标浏览器版本自动将全量引入"babel-polyfill"转换为按需引入（Can I use)。
懒加载
heirloom-static-plugin引入了babel-plugin-syntax-dynamic-import依赖，支持webpack2动态加载：
应用场景示例（react-router懒加载）：
path: '/about',
getComponent: (nextState, cb) => {
import("components/AboutPage").then(module => cb(null, module.default));
},路由到/about时，才会去加载有关的.js文件。