webpack入門（三）webpack的api

終於到了webpack api這一篇，我都等不及了0.0;

webpack is fed a configuration object. Depending on your usage of webpack there are two ways to pass this configuration object:

webpack提供一個配置對象，取決於你咋用webpack，這有兩種辦法pass這個配置對象。

CLI

If you use the CLI it will read a file webpack.config.js (or the file passed by the --config option). This file should export the configuration object:

如果你用CLI，它只認webpack.config.js這個文件，（或者弄一個文件加一個--config的mark），這個文件就導出這個配置對象。

module.exports = {
    // configuration
};

node.js API

If you use the node.js API you need to pass the configuration object as parameter: 用node，，需要將配置對象用參數傳遞進去，如下：

webpack({
    // configuration
}, callback);

multiple configurations

In both cases you can also use an array of configurations, which are processed in parallel. They share filesystem cache and watchers so this is more efficent than calling webpack multiple times.      在這兩種情況下，並行處理，你可以用個配置數組，他們共享文件系統緩存和watchers，比多次webpack調用更有效

CONFIGURATION OBJECT CONTENT

Hint: Keep in mind that you don’t need to write pure JSON into the configuration. Use any JavaScript you want. It’s just a node.js module…

提示：記住，不用在配置里寫純json文件，隨便用js，它就是一個nodejs的模塊

Very simple configuration object example:

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

context

The base directory (absolute path!) for resolving the entry option. If output.pathinfo is set, the included pathinfo is shortened to this directory.

基礎目錄（絕對路徑）用於解決entry這個選項，如果output.pathinfo設置了，就包含了縮短過的目錄；（相當於公共目錄，下面所有的目錄都在這個公共目錄下面）

Default: process.cwd()

entry

The entry point for the bundle.  打包文件的入口

If you pass a string: The string is resolved to a module which is loaded upon startup.      如果傳入一個字符串，這個字符串就會被解析為啟動時加載的模塊。

If you pass an array: All modules are loaded upon startup. The last one is exported.  如果傳入個數組，所有模塊都是啟動時加載，導出最后一個

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

If you pass an object: Multiple entry bundles are created. The key is the chunk name. The value can be a string or an array.

 如果傳入一個對象，就會創建多個輸入包文件，對象鍵值就chunk的name，值可以是字符串或者是數組。

{
    entry: {
        page1: "./page1",
        page2: ["./entry1", "./entry2"]
    },
    output: {
        // Make sure to use [name] or [id] in output.filename
        //  when using multiple entry points
        filename: "[name].bundle.js",
        chunkFilename: "[id].bundle.js"
    }
}

上面傳了一個對象，page1和page2會生成兩個打包文件，名字就是page1.bundle.js和page2.bundle.js，入口文件是3個,page1模塊，entry1和entry2模塊。

output

Options affecting the output of the compilation. output options tell Webpack how to write the compiled files to disk. Note, that while there can be multiple entry points, only one output configuration is specified.

If you use any hashing ([hash] or [chunkhash]) make sure to have a consistent ordering of modules. Use the OccurenceOrderPluginor recordsPath.

 output是影響編譯輸出的選項。output選項告訴webpack怎么把編譯文件寫入磁盤。注意，雖然可以有很多輸入口，但是只有一個輸出配置

如果你用了很多hashing，確保有一個一致的模塊順序。用OccurenceOrderPlugin插件或者 recordsPath

output.filename

Specifies the name of each output file on disk. You must not specify an absolute path here! The output.path option determines the location on disk the files are written to, filename is used solely for naming the individual files.

指定每個輸出文件的名字，你必須要指定一個絕對路徑，output.path 選項決定了文件在磁盤上被寫入的路徑，filename僅被用於命名單個文件

single entry

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

// writes to disk: ./built/bundle.js

打包app.js文件，輸出的bundle.js文件的路徑為./built/bundle.js。

multiple entries    多個入口文件

If your configuration creates more than a single “chunk” (as with multiple entry points or when using plugins like CommonsChunkPlugin), you should use substitutions below to ensure that each file has a unique name.

如果你的配置文件創建了不只一個chunk的時候（就是多個入口文件或者用了 CommonsChunkPlugin插件的時候）（上面這個插件是提取文件公共的的部分，從而形成common的文件），你需要用個標記來確保每個chunk的名字不一樣。下面這個些用於標記

[name] is replaced by the name of the chunk.   [name]在解析時會被替換為chunk的名字

[hash] is replaced by the hash of the compilation. [hash]會被替換成編譯時的hash

[chunkhash] is replaced by the hash of the chunk. [chunkhash]會被替換為chunk的hash

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

輸出為./built/app.js和 ./built/search.js

filename改為chunk會發生什么？

沒錯，就是第一行的hash做名字，綠色的那個文件為輸出。

再換成chunkhash，

生成兩個文件，都是chunk的hash為文件名。

output.path

The output directory as absolute path (required).  output的目錄作為絕對目錄(required)

[hash] is replaced by the hash of the compilation. hash和上面一樣，替換成編譯時的hash值

output.publicPath

The publicPath specifies the public URL address of the output files when referenced in a browser. For loaders that embed <script>or <link> tags or reference assets like images, publicPath is used as the href or url() to the file when it’s different then their location on disk (as specified by path). This can be helpful when you want to host some or all output files on a different domain or on a CDN. The Webpack Dev Server also takes a hint from publicPath using it to determine where to serve the output files from. As with path you can use the [hash] substitution for a better caching profile.

publicPath這個選項當瀏覽器引用時會指定輸出文件的公共url地址。對於嵌入<script>或者<link>標簽或者一些像圖片的資源的loaders來說，當磁盤上的路徑（path指定的路徑）和這里路徑不同，publicPath被作為文件的href或者url。當你想在不同域上輸出一下文件或者在CDN上publicPath很有用，Webpack Dev Server也需要用它來確定服務器的輸出文件。你可以在用path的時候用[hash]替換為一個更好的緩存配置文件。

config.js

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

index.html

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

編譯的路徑就在path寫的絕對路徑里面，引用就可以通過publicPath寫的路徑引用了，下面cdn也是一樣

And a more complicated example of using a CDN and hashes for assets.

一個用CDN和hash資源更復雜的例子

config.js

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

Note: In cases when the eventual publicPath of output files isn’t known at compile time, it can be left blank and set dynamically at runtime in the entry point file. If you don’t know the publicPath while compiling you can omit it and set __webpack_public_path__ on your entry point.

如果最后的publicPath的輸出文件不知道編譯時間，在入口文件中，它可以被留白或者動態的設置運行時間。如果你不知道publicPath可以在編譯時省略，可以在入口文件上設置__webpack_public_path__ 

 __webpack_public_path__ = myRuntimePublicPath

// rest of your application entry

output.chunkFilename

The filename of non-entry chunks as relative path inside the output.path directory.   output.path目錄里的相當路徑做為沒有入口的chunks的名字

[id] is replaced by the id of the chunk.   [id]被替換為chunk的id

[name] is replaced by the name of the chunk (or with the id when the chunk has no name). [name]被替換為chunk的名字(沒名字的時候用它id)

[hash] is replaced by the hash of the compilation.   [hash]被替換為編譯時的hash

[chunkhash] is replaced by the hash of the chunk.   [chunkhash]被替換為每個chunk的hash

output.sourceMapFilename

The filename of the SourceMaps for the JavaScript files. They are inside the output.path directory.sourceMap文件的文件名，他們在output,path的目錄里。

[file] is replaced by the filename of the JavaScript file.這些都和上面一樣。這個選項是為source map功能准備的。

[id] is replaced by the id of the chunk.

[hash] is replaced by the hash of the compilation.

Default: "[file].map"

output.devtoolModuleFilenameTemplate

Filename template string of function for the sources array in a generated SourceMap.

[resource] is replaced by the path used by Webpack to resolve the file, including the query params to the rightmost loader (if any).

[resource]被替換為webpack解析文件的路徑，包括查詢參數的最右邊的loader（如果有）

[resource-path] is the same as [resource] but without the loader query params.

[resource-path]和上面那個一樣，但是不包含loader的查詢參數

[loaders] is the list of loaders and params up to the name of the rightmost loader (only explict loaders).

[loaders]是loaders的目錄和最右邊loader的參數名（只顯示loaders）

[all-loaders] is the list of loaders and params up to the name of the rightmost loader (including automatic loaders).

[all-loaders]同上(包括自動的loaders)

[id] is replaced by the id of the module.

[hash] is replaced by the hash of the module identifier.

[absolute-resource-path] is replaced with the absolute filename.

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

Can also be defined as a function instead of a string template. The function will accept an info object parameter which exposes the following properties:

被定義為函數而不是字符串模板，這個函數接收一個暴露了下面一些屬性的info對象參數。

• identifier
• shortIdentifier
• resource
• resourcePath
• absoluteResourcePath
• allLoaders
• query
• moduleId
• hash

output.devtoolFallbackModuleFilenameTemplate

Similar to output.devtoolModuleFilenameTemplate, but used in the case of duplicate module identifiers.

和 output.devtoolModuleFilenameTemplate相同，但用在重復標識模塊的時候。

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

output.devtoolLineToLine

Enable line to line mapped mode for all/specified modules. Line to line mapped mode uses a simple SourceMap where each line of the generated source is mapped to the same line of the original source. It’s a performance optimization. Only use it if your performance need to be better and you are sure that input lines match which generated lines.

為所有模塊啟用行映射模式，行映射模式用了一個簡單的SourceMap，用在了每一行生成的source映射到原始的source，這是一個性能優化，僅用在你的性能需要更佳，你確定輸入行對應生成行的時候。

true enables it for all modules (not recommended)

true： 用在所有模塊(不建議)

An object {test, include, exclude} similar to module.loaders enables it for specific files.

Default: disabled

output.hotUpdateChunkFilename

The filename of the Hot Update Chunks. They are inside the output.path directory.

熱替換chunks的文件名。

[id] is replaced by the id of the chunk.

[hash] is replaced by the hash of the compilation. (The last hash stored in the records)

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

output.hotUpdateMainFilename

The filename of the Hot Update Main File. It is inside the output.path directory.  熱替換主文件的的名字。在output.path目錄里。

[hash] is replaced by the hash of the compilation. (The last hash stored in the records)

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

output.jsonpFunction

The JSONP function used by webpack for asnyc loading of chunks.  jsonp函數被用於webpack異步加載chunks

A shorter function may reduce the filesize a bit. Use different identifier, when having multiple webpack instances on a single page.

一個精簡的函數會減少很大的文件大小，當在單頁中有多個webpack實例的時候用不同的標識。

Default: "webpackJsonp"

output.hotUpdateFunction

The JSONP function used by webpack for async loading of hot update chunks.

jsonp函數用於被用於webpack異步加載熱替換的chunks

Default: "webpackHotUpdate"

output.pathinfo

Include comments with information about the modules.

包含一些模塊的評論信息。

require(/* ./test */23)

Do not use this in production.

不要在生產環境下使用

Default: false

output.library

If set, export the bundle as library. output.library is the name.    如果設置了，導出的包就是庫，名字為output.library

Use this, if you are writing a library and want to publish it as single file.      如果你寫一個庫，想發布為一個文件就用此選項。

output.libraryTarget

Which format to export the library:  導出庫的格式

"var" - Export by setting a variable: var Library = xxx (default)        通過設置一個變量導出

"this" - Export by setting a property of this: this["Library"] = xxx      通過設置this的屬性導出

"commonjs" - Export by setting a property of exports: exports["Library"] = xxx   通過exports的屬性導出

"commonjs2" - Export by setting module.exports: module.exports = xxx          通過設置module.exports導出

"amd" - Export to AMD (optionally named - set the name via the library option)   通過amd導出

"umd" - Export to AMD, CommonJS2 or as property in root

Default: "var"

If output.library is not set, but output.libraryTarget is set to a value other than var, every property of the exported object is copied (Except amd, commonjs2 and umd).

如果output.library沒設置，但是output.libraryTarget設置了不是var的值，導出對象的每個屬性都會被拷貝。(除了amd common.js2 和Umd)

output.umdNamedDefine

If output.libraryTarget is set to umd and output.library is set, setting this to true will name the AMD module.

如果output.libraryTarget設置為umd， output.library設置了，這個選項設為true將會給命名給amd模塊

output.sourcePrefix

Prefixes every line of the source in the bundle with this string.

每行包文件的源文件的前綴都是字符串

Default: "\t"

output.crossOriginLoading

This option enables cross-origin loading of chunks.   這個選項用於跨域加載chunks

Possible values are:    

false - Disable cross-origin loading.      設為false禁止跨域加載

"anonymous" - Cross-origin loading is enabled. When using anonymous no credentials will be send with the request.

允許跨域加載，用anonymous的時候，不會在請求發送證書。

"use-credentials" - Cross-origin loading is enabled and credentials will be send with the request.

允許跨域加載，會在請求中發送證書

For more information on cross-origin loading see MDN

Default: false