docs: 翻译完了 build 部分

2018-10-26 11:15:03 +08:00 · 2018-10-26 11:15:03 +08:00 · 845161839f
commit 845161839f
parent e9737703ea
1 changed files with 241 additions and 21 deletions
--- a/aio/content/guide/build.md
+++ b/aio/content/guide/build.md
@ -1,28 +1,48 @@
 # Building and serving Angular apps

+# 构建并运行 Angular 应用
+
 This page discusses build-specific configuration options for Angular projects.

+本文讨论的是 Angular 应用中与构建相关的配置项。
+
 {@a app-environments}

 ## Configuring application environments

+## 配置应用环境
+
 You can define different named build configurations for your project, such as *stage* and *production*, with different defaults. 

+你可以用不同的默认值来为项目定义出不同的命名配置项，比如 *stage* 和 *production*。
+
 Each named build configuration can have defaults for any of the options that apply to the various build targets, such as `build`, `serve`, and `test`. The [Angular CLI](cli) `build`, `serve`, and `test` commands can then replace files with appropriate versions for your intended target environment.

+每个命名配置项都可以具有某些选项的默认值，并应用于各种构建目标，比如 `build`、`serve` 和 `test`。
+[Angular CLI](cli)  的 `build`、`serve` 和 `test` 命令可以为不同的目标环境，把文件替换成合适的版本。
+
 The following figure shows how a project has multiple build targets, which can be executed using the named configurations that you define.

+下面的例子展示了项目如何拥有多个构建目标，可以使用你定义的明明配置来执行这些目标。
+
 <figure>
  <img src="generated/images/guide/build/build-config-targets.gif" alt="build configurations and targets">
 </figure>

 ### Configure environment-specific defaults

+### 配置针对特定环境的默认值
+
 A project's `src/environments/` folder contains the base configuration file, `environment.ts`, which provides a default environment. 
 You can add override defaults for additional environments, such as production and staging, in target-specific configuration files. 

+项目的 `src/environments/` 文件夹包含基础配置文件 `environment.ts`，它提供了一个默认环境。
+你可以在针对特定目标的配置文件中，为其它环境（比如生产和预生产）覆盖这些默认值。
+
 For example:

+比如：
+
 ```
 └──myProject/src/environments/
                   └──environment.ts
@ -32,6 +52,8 @@ For example:

 The base file `environment.ts`, contains the default environment settings. For example:

+基础环境 `environment.ts` 包含了默认的环境设置。比如：
+
 <code-example language="none" class="code-shell">
 export const environment = {
  production: false
@ -42,6 +64,10 @@ The `build` command uses this as the build target when no environment is specifi
 You can add further variables, either as additional properties on the environment object, or as separate objects. 
 For example, the following adds a default for a variable to the default environment:

+当没有制定环境时，`build` 命令就会用它作为构建目标。
+你可以添加其它变量，可以用该环境对象附加属性的形式，也可以用独立对象的形式。
+比如：以下内容将会把一个变量添加到默认环境中：
+
 ```
 export const environment = {
  production: false,
@ -52,6 +78,9 @@ export const environment = {
 You can add target-specific configuration files, such as `environment.prod.ts`. 
 The following sets content sets default values for the production build target:

+你可以添加针对特定目标的配置文件，比如 `environment.prod.ts`。
+下面的代码会设置针对生产环境构建目标的默认值：
+
 ```
 export const environment = {
  production: true
@ -61,8 +90,12 @@ export const environment = {

 ### Using environment-specific variables in your app

+### 在应用中使用针对特定环境的变量
+
 The following application structure configures build targets for production and staging environments:

+下面的应用结构会为生产和预生产环境配置构建目标：
+
 ```
 └── src
    └── app
@ -76,14 +109,20 @@ The following application structure configures build targets for production and

 To use the environment configurations you have defined, your components must import the original environments file:

+要使用已定义的配置环境，组件必须导入原始版的环境文件：
+
 ```
 import { environment } from './../environments/environment';
 ```

 This ensures that the build and serve commands can find the configurations for specific build targets.

+这会确保 `build` 和 `serve` 命令能找到针对特定目标的配置。
+
 The following code in the component file (`app.component.ts`) uses an environment variable defined in the configuration files.

+组件文件（`app.component.ts`）中的下列代码可以使用该配置文件中定义的环境变量。
+
 ```
 import { Component } from '@angular/core';
 import { environment } from './../environments/environment';
@ -104,13 +143,21 @@ export class AppComponent {

 ## Configure target-specific file replacements

+## 配置针对特定目标的文件替换规则
+
 The main CLI configuration file, `angular.json`, contains a `fileReplacements` section in the configuration for each build target, which allows you to replace any file with a target-specific version of that file. 
 This is useful for including target-specific code or variables in a build that targets a specific environment, such as production or staging.

+CLI 的主配置文件 `angular.json` 中的每个构建目标下都包含了一个 `fileReplacements` 区段。这能让你把任何文件替换为针对特定目标的版本。
+当构建目标需要包含针对特定环境（比如生产或预生产）的代码或变量时，这非常有用。
+
 By default no files are replaced. 
 You can add file replacements for specific build targets. 
 For example:

+默认情况下不会替换任何文件。
+你可以为特定的构建目标添加文件替换规则。比如：
+
 ```
 "configurations": {
  "production": {
@ -125,8 +172,12 @@ For example:

 This means that when you build your production configuration (using `ng build --prod` or `ng build --configuration=production`), the `src/environments/environment.ts` file is replaced with the target-specific version of the file, `src/environments/environment.prod.ts`.

+这意味着当你构建生产配置时（用 `ng build --prod` 或 `ng build --configuration=production`），就会把 `src/environments/environment.ts` 文件替换成针对特定目标的版本 `src/environments/environment.prod.ts`。
+
 You can add additional configurations as required. To add a staging environment, create a copy of `src/environments/environment.ts` called `src/environments/environment.staging.ts`, then add a `staging` configuration to `angular.json`:

+你还可以按需添加更多配置文件。要想添加预生产环境，把 `src/environments/environment.ts` 复制为 `src/environments/environment.staging.ts`，然后在 `angular.json` 中添加 `staging` 配置：
+
 ```
 "configurations": {
  "production": { ... },
@ -144,10 +195,17 @@ You can add additional configurations as required. To add a staging environment,
 You can add more configuration options to this target environment as well. 
 Any option that your build supports can be overridden in a build target configuration.

+你还可以往目标环境中添加更多配置项。
+你的构建目标支持的任何选项都可以在构建目标配置中进行覆盖。
+
 To build using the staging configuration, run `ng build --configuration=staging`.

+要想使用预生产环境进行构建，请运行 `ng build --configuration=staging`。
+
 You can also configure the `serve` command to use the targeted build configuration if you add it to the "serve:configurations" section of `angular.json`:

+如果将其添加到 `angular.json` 的 "serve:configurations" 区段，你还可以配置 `serve` 命令来使用 目标构建配置：
+
 ```
 "serve": {
  "builder": "@angular-devkit/build-angular:dev-server",
@ -169,11 +227,18 @@ You can also configure the `serve` command to use the targeted build configurati

 ## Configure size budgets

+## 配置文件大小预算
+
 As applications grow in functionality, they also grow in size. 
 The CLI allows you to set size thresholds in your configuration to ensure that parts of your application stay within size boundaries that you define.

+当应用的功能不断增长时，其文件大小也会同步增长。
+CLI 允许你通过配置项来限制文件大小，以确保应用的各个部分都处于你定义的大小范围内。
+
 Define your size boundaries in the CLI configuration file, `angular.json`, in a `budgets` section for each [configured environment](#app-environments). 

+你可以在 CLI 配置文件 `angular.json` 的 `budgets` 区段为每个[所配置的环境](#app-environments)定义这些大小范围。
+
 ```
 {
  ...
@ -190,35 +255,72 @@ You can specify size budgets for the entire app, and for particular parts.
 Each budget entry configures a budget of a given type. 
 Specify size values in the following formats:

+你可以为整个应用指定大小范围，也可以为特定部分。
+每个条目会为一种特定的类型配置大小范围。
+用下列各式来指定大小的值：
+
 * 123 or 123b: Size in bytes

+  123 或 123b：以字节为单位的大小
+
 * 123kb: Size in kilobytes

+  123kb：以 kb 为单位的大小
+
 * 123mb: Size in megabytes

+  123mb：以 mb 为单位的大小
+
 * 12%: Percentage of size relative to baseline. (Not valid for baseline values.)

+  12%：相对于基准大小的百分比大小。（不能用作基准大小的值。）
+
 When you configure a budget, the build system warns or reports and error when a given part of the app reaches or exceeds a boundary size that you set.

+如果配置了大小范围，构建系统就会在发现应用的某个部分达到或超过了你设置的大小范围时发出警告或报错。
+
 Each budget entry is a JSON object with the following properties:

+每个范围条目是一个 JSON 对象，它具有下列属性：
+
 <table>
  <tr>
-    <th>Property</th>
-    <th>Value</th>
+    <th><t>Property</t><t>属性</t></th>
+    <th><t>Value</t><t>值</t></th>
  </tr>

  <tr>
    <td>type</td>
-    <td>The type of budget. One of:
+    <td>
+    
+    The type of budget. One of:
+    
+    限制的类型。有效值为：

        * bundle - The size of a specific bundle.
+        
+          bundle - 特定包的大小。
+        
        * initial - The initial size of the app.
+        
+          initial -  应用的初始大小。
+        
        * allScript - The size of all scripts.
+        
+          allScript - 所有脚本的总大小。
+        
        * all - The size of the entire app.
+        
+          all - 整个应用的总大小。
+        
        * anyScript - The size of any one script.
+        
+          anyScript - 任何一个脚本的大小。
+        
        * any - The size of any file.
        
+          any - 任何一个文件的大小。
+          
    </td>
  </tr>
   <tr>
@ -227,35 +329,79 @@ Each budget entry is a JSON object with the following properties:
    
    The name of the bundle (for `type=bundle`).
    
+    要限制的包的名字（当 `type=bundle` 时）。
+    
    </td>
  </tr>
  <tr>
    <td>baseline</td>
-    <td>An absolute baseline size for percentage values. </td>
+    <td>
+    
+    An absolute baseline size for percentage values. 
+    
+    一个表示基准大小的绝对值，用做比例值的基数。
+    
+    </td>
  </tr>
  <tr>
    <td>maximumWarning</td>
-    <td>Warns when a size exceeds this threshold percentage of the baseline.</td>
+    <td>
+
+    Warns when a size exceeds this threshold percentage of the baseline.
+
+    当大小超过基线的这个阈值百分比时给出警告。
+
+    </td>
  </tr>
  <tr>
    <td>maximumError</td>
-    <td>Reports an error when the size exceeds this threshold percentage of the baseline.</td>
+    <td>
+
+    Reports an error when the size exceeds this threshold percentage of the baseline.
+
+    当大小超过基线的这个阈值百分比时报错。
+
+    </td>
  </tr>
  <tr>
    <td>minimumWarning</td>
-    <td>Warns when the size reaches this threshold percentage of the baseline.</td>
+    <td>
+
+    Warns when the size reaches this threshold percentage of the baseline.
+
+    当大小小于基线的这个阈值百分比时给出警告。
+
+    </td>
  </tr>
  <tr>
    <td>minimumError</td>
-    <td>Reports an error when the size reaches this threshold percentage of the baseline.</td>
+    <td>
+
+    Reports an error when the size reaches this threshold percentage of the baseline.
+
+    当大小小于基线的这个阈值百分比时报错。
+
+    </td>
  </tr>
  <tr>
    <td>warning</td>
-    <td>Warns when the size ??reaches or exceeds?? this threshold percentage of the baseline.</td>
+    <td>
+
+    Warns when the size ??reaches or exceeds?? this threshold percentage of the baseline.
+
+    当大小小于或超过基线的这个阈值百分比时都给出警告。
+
+    </td>
  </tr>
  <tr>
    <td>error</td>
-    <td>Reports an error when the size ??reaches or exceeds?? this threshold percentage of the baseline.</td>
+    <td>
+
+    Reports an error when the size ??reaches or exceeds?? this threshold percentage of the baseline.
+
+    当大小小于或超过基线的这个阈值百分比时都报错。
+
+    </td>
  </tr>

 </table>
@ -265,35 +411,57 @@ Each budget entry is a JSON object with the following properties:

 ## Configuring browser compatibility

+## 配置浏览器兼容性
+
 The CLI uses [Autoprefixer](https://github.com/postcss/autoprefixer) to ensure compatibility with different browser and browser versions. 
 You may find it necessary to target specific browsers or exclude certain browser versions from your build.

+CLI 使用 [Autoprefixer](https://github.com/postcss/autoprefixer) 来确保对不同浏览器及其版本的兼容性。
+你会发现当你要从构建中针对特定的目标浏览器或排除指定的浏览器版本时，这是很有必要的。
+
 Internally, Autoprefixer relies on a library called [Browserslist](https://github.com/browserslist/browserslist) to figure out which browsers to support with prefixing. 
 Browserlist looks for configuration options in a `browserlist` property of the package configuration file, or in a configuration file named `.browserslistrc`. 
 Autoprefixer looks for the Browserlist configuration when it prefixes your CSS. 

+在内部 Autoprefixer 依赖一个名叫 [Browserslist](https://github.com/browserslist/browserslist) 的库来指出需要为哪些浏览器加前缀。
+Browserlist 会在 `package.json` 的 `browserlist` 属性中或一个名叫 `.browserslistrc` 的配置文件中来配置这些选项。
+当 Autoprefixer 为你的 CSS 加前缀时，就会查阅 Browserlist 的配置。
+
 * You can tell Autoprefixer what browsers to target by adding a browserslist property to the package configuration file, `package.json`:
-```
- "browserslist": [
-   "> 1%",
-   "last 2 versions"
- ]
-```
+
+  你可以为 `package.json` 添加 `browserslist` 属性来告诉 Autoprefixer，要针对哪些浏览器：
+
+  ```
+   "browserslist": [
+     "> 1%",
+     "last 2 versions"
+   ]
+  ```

 * Alternatively, you can add a new file, `.browserslistrc`, to the project directory, that specifies browsers you want to support:
-```
- ### Supported Browsers
- > 1%
- last 2 versions
-```
+
+  或者你也可以在项目目录下添加一个新文件 `.browserslistrc`，用于指定你要支持哪些浏览器： 
+
+  ```
+   ### Supported Browsers
+   > 1%
+   last 2 versions
+  ```

 See the [browserslist repo](https://github.com/browserslist/browserslist) for more examples of how to target specific browsers and versions.

+参见 [browserslist 的代码库](https://github.com/browserslist/browserslist)以得到如何指定浏览器及其版本的更多例子。
+
 <div class="alert is-helpful">
+
 Backward compatibility

+向后兼容
+
 If you want to produce a progressive web app and are using [Lighthouse](https://developers.google.com/web/tools/lighthouse/) to grade the project, add the following browserslist entry to your `package.json` file, in order to eliminate the [old flexbox](https://developers.google.com/web/tools/lighthouse/audits/old-flexbox) prefixes:

+如果你要制作渐进式应用，并使用 [Lighthouse](https://developers.google.com/web/tools/lighthouse/) 来对该项目进行评分，请为 `package.json` 添加如下的 `browserslist` 条目，以消除[老版本的 flexbox](https://developers.google.com/web/tools/lighthouse/audits/old-flexbox) 前缀：
+
 ```
 "browserslist": [
  "last 2 versions",
@ -308,12 +476,22 @@ If you want to produce a progressive web app and are using [Lighthouse](https://

 ## Proxying to a backend server

+## 代理到后端服务器
+
 You can use the [proxying support](https://webpack.js.org/configuration/dev-server/#devserver-proxy) in the `webpack` dev server to divert certain URLs to a backend server, by passing a file to the `--proxy-config` build option.
 For example, to divert all calls for `http://localhost:4200/api` to a server running on `http://localhost:3000/api`, take the following steps.

+你可以使用 `webpack` 开发服务器中的[代理支持](https://webpack.js.org/configuration/dev-server/#devserver-proxy)来把特定的 URL 转发给后端服务器，只要传入 `--proxy-config` 选项就可以了。
+比如，要把所有到 `http://localhost:4200/api` 的调用都转给运行在 `http://localhost:3000/api` 上的服务器，可采取如下步骤。
+
 1. Create a file `proxy.conf.json` in the projects `src/` folder, next to `package.json`.

+   在项目的 `src/` 目录下创建一个 `proxy.conf.json` 文件，紧挨着 `package.json`。
+
 1. Add the following content to the new proxy file:
+
+   往这个新的代理配置文件中添加如下内容：
+
    ```
    {
      "/api": {
@ -324,6 +502,9 @@ For example, to divert all calls for `http://localhost:4200/api` to a server run
    ```

 1. In the CLI configuration file, `angular.json`, add the `proxyConfig` option to the `serve` target:
+
+   在 CLI 配置文件 `angular.json` 中为 `serve` 目标添加 `proxyConfig` 选项：
+
    ```
    ...
    "architect": {
@ -338,16 +519,28 @@ For example, to divert all calls for `http://localhost:4200/api` to a server run

 1. To run the dev server with this proxy configuration, call `ng serve`. 

+   要使用这个代理选项启动开发服务器，请运行 `ng serve` 命令。
+
 You can edit the proxy configuration file to add configuration options; some examples are given below. 
 For a description of all options, see [webpack DevServer documentation](https://webpack.js.org/configuration/dev-server/#devserver-proxy).

+你可以编辑这个代理配置文件，以添加配置项，例子如下。
+要查看所有选项的详细说明，参见 [webpack DevServer 文档](https://webpack.js.org/configuration/dev-server/#devserver-proxy)。
+
 Note that if you edit the proxy configuration file, you must relaunch the `ng serve` process to make your changes effective.

+注意，如果你编辑了这个代理配置文件，就必须重启 `ng serve`，来让你的修改生效。
+
 ### Rewrite the URL path

+### 重写 URL 路径
+
 The `pathRewrite` proxy configuration option lets you rewrite the URL path at run time. 
 For example, you can specify the following `pathRewrite` value to the proxy configuration to remove "api" from the end of a path.

+`pathRewrite` 代理配置项能让你在运行时重写 URL 路径。
+比如，你可以在代理配置中指定如下的 `pathRewrite` 值，以移除路径末尾的 "api" 部分。
+
 ```
 {
  "/api": {
@ -362,6 +555,8 @@ For example, you can specify the following `pathRewrite` value to the proxy conf

 If you need to access a backend that is not on `localhost`, set the `changeOrigin` option as well. For example:

+如果你要访问的后端不在 `localhost` 上，还要设置 `changeOrigin` 选项。比如：
+
 ```
 {
  "/api": {
@ -377,6 +572,8 @@ If you need to access a backend that is not on `localhost`, set the `changeOrigi

 To help determine whether your proxy is working as intended, set the `logLevel` option. For example:

+要想了解你的代理是否在如预期般工作，可以设置 `logLevel` 选项。比如：
+
 ```
 {
  "/api": {
@ -392,12 +589,20 @@ To help determine whether your proxy is working as intended, set the `logLevel`

 Proxy log levels are `info` (the default), `debug`, `warn`, `error`, and `silent`.

+代理的有效日志级别是 `info`（默认值）、`debug`、`warn`、`error` 和 `silent`。
+
 ### Proxy multiple entries

+### 代理多个条目
+
 You can  proxy multiple entries to the same target by defining the configuration in JavaScript.

+通过用 JavaScript 定义此配置，你还可以把多个条目代理到同一个目标。
+
 Set the proxy configuration file to `proxy.conf.js` (instead of `proxy.conf.json`), and specify configuration files as in the following example.

+将代理配置文件设置为 `proxy.conf.js`（代替 `proxy.conf.json`），并指定如下例子中的配置文件。
+
 ```
 const PROXY_CONFIG = [
    {
@ -420,6 +625,8 @@ module.exports = PROXY_CONFIG;

 In the CLI configuration file, `angular.json`, point to the JavaScript proxy configuration file:

+在 CLI 配置文件 `angular.json` 中，指向 JavaScript 配置文件：
+
 ```
 ...
 "architect": {
@ -434,8 +641,12 @@ In the CLI configuration file, `angular.json`, point to the JavaScript proxy con

 ### Bypass the proxy

+### 绕过代理
+
 If you need to optionally bypass the proxy, or dynamically change the request before it's sent, add the bypass option, as shown in this JavaScript example.

+如果你需要根据情况绕过此代理，或在发出请求前先动态修改一下，可以添加 `bypass` 选项，就像下例的 JavaScript 所示。
+
 ```
 const PROXY_CONFIG = {
    "/api/proxy": {
@ -456,17 +667,26 @@ module.exports = PROXY_CONFIG;

 ### Using corporate proxy

+### 使用公司代理
+
 If you work behind a corporate proxy, the cannot directly proxy calls to any URL outside your local network. 
 In this case, you can configure the backend proxy to redirect calls through your corporate proxy using an agent:

+如果你在公司代理后面工作，就无法直接代理到局域网之外的任何 URL。
+这种情况下，你可以把这个后端代理配置为，借助 agent 通过你的公司代理转发此调用：
+
 <code-example language="none" class="code-shell">
 npm install --save-dev https-proxy-agent
 </code-example>

 When you define an environment variable `http_proxy` or `HTTP_PROXY`, an agent is automatically added to pass calls through your corporate proxy when running `npm start`.

+如果你定义了环境变量 `http_proxy` 或 `HTTP_PROXY`，当运行 `npm start` 时，就会自动添加一个 agent 来通过你的企业代理转发网络调用。
+
 Use the following content in the JavaScript configuration file.

+请在 JavaScript 配置文件中使用如下内容。
+
 ```
 var HttpsProxyAgent = require('https-proxy-agent');
 var proxyConfig = [{