[译]webpack API之配置（上）

webpack中的配置对象（configuration object），根据你使用webpack的不同有两种方式传入这个对象：

CLI

如果你使用了CLI ，将会读取webpack.config.js文件（或是由 --config 选项传入的文件）。该文件以一下形式暴露配置对象（configuration object）：

module.exports = {
    // configuration
};

node.js API

如果你使用node.js API，那么你将需要把配置对象（configuration object作为参数传入：

webpack({
    // configuration
}, callback);

多个配置

你也传入一个由多个配置对象组成的数组，彼此之间是平行执行的。他们共享文件系统的缓存与监听。因此这将比多次调用webpack来的更有效率。

配置对象的内容

小贴士：在配置中你并不需要使用纯的JSON 。使用任何你想用的JavaScript 格式。因为配置文件是一个node.js模块。

一个超简单的配置对象例子：

{
    context: __dirname + "/app",
    entry: "./entry",
    output: {
        path: __dirname + "/dist",
        filename: "bundle.js"
    }
}

context参数：

用于决定entry参数的基本目录（绝对路径）。如果设置了output.pathinfo，包括其在内都会被设置为这个目录。

Default: process.cwd()

entry参数

打包的入口位置。

如果传入一个字符串：这个字符串将决定启动时被加载的那个模块。

如果传入一个数组：所有的模块在启动时都将被加载。并把最后一个作为出口。

entry: ["./entry1", "./entry2"]

如果传入一个对象：将会创建多个entry束（bundle）。key就是区块的名字，value可以时字符串或是数组。

{
    entry: {
        page1: "./page1",
        page2: ["./entry1", "./entry2"]
    },
    output: {
        // 当你有多个入口文件时，请确保在output.filename中使用 [name]或[id] 
        filename: "[name].bundle.js",
        chunkFilename: "[id].bundle.js"
    }
}

output参数

该选项将影响编译的结果。output将控制Webpack将编译后的文件写入磁盘的过程。请注意，即便可以存在多个入口点，但也仅需要规定一个output 即可。

当你使用哈希（[hash] 或 [chunkhash]）时，请确保你模块的有固定的顺序。可使用OccurenceOrderPlugin或recordsPath。

output.filename

该参数指定了磁盘中每一个输出文件的名字。不能在此指定绝对路径！output.path选项将决定文件被写入磁盘的位置，filename被用来单独处理每个文件的命名。（译注：这里其实强调了解耦）

单入口：

{
  entry: './src/app.js',
  output: {
    filename: 'bundle.js',
    path: './built'
  }
}

// 写入磁盘路径： ./built/bundle.js

多入口

如果你的配置项会创建不知一个“chunk”（例如使用多个入口文件或使用像CommonsChunkPlugin这样的插件），你将会用到以下置换以确保每个文件不重名。

[name] 将被替换成chunk的名字。
[hash] 将被替换成编译时的hash。

[chunkhash] 将被替换为chunk的hash。

{
  entry: {
    app: './src/app.js',
    search: './src/search.js'
  },
  output: {
    filename: '[name].js',
    path: __dirname + '/built'
  }
}

// 写入磁盘路径： ./built/app.js, ./built/search.js

output.path

该选项设置了output目录，并且要是一个绝对路径。

[hash] 将被替换成编译时的hash。

output.publicPath

该选项定义了在浏览器中引用时输出文件使用的公共url地址。对于内嵌的<script> 或 <link>标签亦或图片资源的引用，publicPath被用来以href 或 url()指向文件，当它不同于它们在磁盘上的位置（由路径指定）。当你想要把一些或全部文件部署在不同域或CND上时，publicPath将变得很有帮助。Webpack Dev Server也通过publicPath来确定服务器的文件引用。与上文的path一样，你可以使用[hash]置换来得到更好的缓存配置。

config.js

output: {
    path: "/home/proj/public/assets",
    publicPath: "/assets/"
}

index.html

<head>
  <link href="/assets/spinner.gif"/>
</head>

一个更复杂的例子来说明对资源使用CDN和哈希。

config.js

output: {
    path: "/home/proj/cdn/assets/[hash]",
    publicPath: "http://cdn.example.com/assets/[hash]/"
}

注意：在本例中，编译时并不知晓最终输出文件的publicPath，在入口文件中，其被留作空白，并在运行时动态设置。如果在编译时不清楚publicPath，你可以忽略它或是在入口文件中设置webpack_public_path 。

__webpack_public_path__ = myRuntimePublicPath

// 应用入口的其余部分

output.chunkFilename

作为output.path目录中相关路径的无入口块的文件名。

[id] 将被替换成chunk的id。
[name] 将被替换成chunk的名字（当区块没有名字时用id表示）。
[hash] 将被替换成编译时的哈希。
[chunkhash] 将被替换成chunk的哈希。

output.sourceMapFilename

js文件的SourceMaps文件名。他们存在于output.path目录中。

[file] 将被替换js文件的文件名。
[id] 将被替换成chunk的id。
[hash] 将被替换成编译时的哈希。

Default: "[file].map"

output.devtoolModuleFilenameTemplate

在生成SourceMap时的函数的文件名模版字符串。

[resource] 将被替换成webpack解析文件的路径，包括最右边loader的查询参数（如果存在）。
[resource-path] 相当于缺少数据查询loader的 [resource] 。
[loaders] 是loaders 的目录，也是最右边loader的参数名（只显示loaders）is the list of loaders and params up to the name of the rightmost loader (only explict loaders).
[all-loaders] 是loaders 的目录，也是最右边loader的参数名（包含自动化的loader）
[id] 将被替换成模块的id。
[hash] 将被替换成模块识别码的哈希。
[absolute-resource-path] 将被替换成绝对的文件名。

Default (devtool=[inline-]source-map): "webpack:///[resource-path]"
Default (devtool=eval): "webpack:///[resource-path]?[loaders]"
Default (devtool=eval-source-map): "webpack:///[resource-path]?[hash]"

也可以定义为函数而不是字符串模板。函数接受包含如下属性的对象作为参数。

identifier
shortIdentifier
resource
resourcePath
absoluteResourcePath
allLoaders
query
moduleId
hash

output.devtoolFallbackModuleFilenameTemplate

与output.devtoolModuleFilenameTemplate相似，但用于处理复制的模版标识符。

Default: "webpack:///[resourcePath]?[hash]"

output.hotUpdateChunkFilename

热更新块的文件名。存在于output.path目录中。

[id] 将被替换为块的id。
[hash] 将被替换为编译时的哈希（在记录中存在的最后一个哈希）。

Default: "[id].[hash].hot-update.js"

output.hotUpdateMainFilename

热加载主文件的文件名。存在于output.path目录中。

[hash] 将被替换为编译时的哈希（在记录中存在的最后一个哈希）。

Default: "[hash].hot-update.json"

output.jsonpFunction

被用于webpack异步加载块的JSONP函数。

一个更短的函数将从一定意义上减小文件大小。当单页中有多个webpack实例时，使用不同的标识符。

Default: "webpackJsonp"

output.hotUpdateFunction

被用于webpack异步加载热更新块的JSONP函数。

Default: "webpackHotUpdate"

output.pathinfo

包含模块的评论信息。

require(/* ./test */23)

在生产环境中不要使用。

Default: false

output.library

若你设置了该选项，则导出文件是一个库，库名为output.library所设。
如果你的目的是写一个库并且想要将其发布为一个单一的文件，就是用它。

output.libraryTarget

导出库的格式：

"var" - 通过设置变量导出：

var Library = xxx (default)

"this" - 通过设置this属性导出：

this["Library"] = xxx

"commonjs" - 通过设置export属性导出：

exports: exports["Library"] = xxx

"commonjs2" - 通过设置module.exports 导出：

module.exports = xxx

"amd" - 通过AMD（可选：通过library选项设置）导出

"umd" - 通过AMD，CommonJS2或在根中的属性导出。

Default: "var"

如果没有设置output.library，并且output.libraryTarget没有通过var设置值。暴露出的对象的每个属性都会被拷贝（除了amd, commonjs2 和 umd）。

output.umdNamedDefine

如果在output.libraryTarget被设置成umd形式，并且output.library也被设置时，将该选项设为true将会给命名给amd模块

output.sourcePrefix

每行包文件的资源的前缀都是字符串。

Default: "\t"

output.crossOriginLoading

该选项跨域加载块。

有如下可能的值：

false - 静止跨域加载。

"anonymous" - 允许跨域加载。没有证书将会在请求时被发送。

"use-credentials" - 允许跨域加载。证书将会在请求时被发送。

可以在MDN上查看更多关于跨域的信息。

Default: false

译注：由于篇幅有限，把文档拆成两篇，下篇随后奉上。

[译]webpack API之配置（上）

CLI

node.js API

多个配置

配置对象的内容

context参数：

entry参数

output参数

output.filename

单入口：

多入口

output.path

output.publicPath

config.js

index.html

config.js

output.chunkFilename

output.sourceMapFilename

output.devtoolModuleFilenameTemplate

output.devtoolFallbackModuleFilenameTemplate

output.hotUpdateChunkFilename

output.hotUpdateMainFilename

output.jsonpFunction

output.hotUpdateFunction

output.pathinfo

output.library

output.libraryTarget

output.umdNamedDefine

output.sourcePrefix

output.crossOriginLoading

这是上帝的杰作

引用和评论

如何实现水面波动？一种代码实现两种效果【shader 奇技淫巧】

webpack的入门教程

前端微服务跨域配置解决办法，devServer为例

如何使用Visual Studio Code调试PHP CLI应用和Web应用

开发自定义Taro插件解决跨平台难题

使用基于 WebRTC 的 JavaScript API 在浏览器环境里调用本机摄像头

macOS上HBuildX 开发 uni-app项目，运行调试时编辑保存文件不会自动编译更新页面