24 KiB

Raw Blame History

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 build, serve, and test commands can then replace files with appropriate versions for your intended target environment.

每个命名配置项都可以具有某些选项的默认值，并应用于各种构建目标，比如 build、serve 和 test。 Angular 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.

下面的例子展示了项目如何拥有多个构建目标，可以使用你定义的明明配置来执行这些目标。

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
                   └──environment.prod.ts
                   └──environment.stage.ts

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

基础环境 environment.ts 包含了默认的环境设置。比如：

export const environment = {
  production: false
};

The build command uses this as the build target when no environment is specified. 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,
  apiUrl: 'http://my-api-url'
};

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
  apiUrl: 'http://my-prod-url'
};

Using environment-specific variables in your app

在应用中使用针对特定环境的变量

The following application structure configures build targets for production and staging environments:

下面的应用结构会为生产和预生产环境配置构建目标：

└── src
    └── app
        ├── app.component.html
        └── app.component.ts
    └── environments
        ├── environment.prod.ts
        ├── environment.staging.ts
        └── environment.ts

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';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  constructor() {
    console.log(environment.production); // Logs false for default environment
  }
  title = 'app works!';
}

{@a file-replacement}

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": {
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.prod.ts"
      }
    ],
    ...

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": { ... },
  "staging": {
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.staging.ts"
      }
    ]
  }
}

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 the following command:

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",
  "options": {
    "browserTarget": "your-project-name:build"
  },
  "configurations": {
    "production": {
      "browserTarget": "your-project-name:build:production"
    },
    "staging": {
      "browserTarget": "your-project-name:build:staging"
    }
  }
},

{@a size-budgets}

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.

你可以在 CLI 配置文件 angular.json 的 budgets 区段为每个所配置的环境定义这些大小范围。

{
  ...
  "configurations": {
    "production": {
      ...
      budgets: []
    }
  }
}

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 对象，它具有下列属性：

Property	Value
属性	值
type	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>
name	The name of the bundle (for `type=bundle`). 要限制的包的名字（当 `type=bundle` 时）。 </td>
baseline	`An absolute baseline size for percentage values. 一个表示基准大小的绝对值，用做比例值的基数。 </td>`
maximumWarning	`Warns when a size exceeds this threshold percentage of the baseline. 当大小超过基线的这个阈值百分比时给出警告。 </td>`
maximumError	`Reports an error when the size exceeds this threshold percentage of the baseline. 当大小超过基线的这个阈值百分比时报错。 </td>`
minimumWarning	`Warns when the size reaches this threshold percentage of the baseline. 当大小小于基线的这个阈值百分比时给出警告。 </td>`
minimumError	`Reports an error when the size reaches this threshold percentage of the baseline. 当大小小于基线的这个阈值百分比时报错。 </td>`
warning	`Warns when the size ??reaches or exceeds?? this threshold percentage of the baseline. 当大小小于或超过基线的这个阈值百分比时都给出警告。 </td>`
error	`Reports an error when the size ??reaches or exceeds?? this threshold percentage of the baseline. 当大小小于或超过基线的这个阈值百分比时都报错。 </td>`

{@a browser-compat}

Configuring browser compatibility

配置浏览器兼容性

The CLI uses 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 来确保对不同浏览器及其版本的兼容性。你会发现当你要从构建中针对特定的目标浏览器或排除指定的浏览器版本时，这是很有必要的。

Internally, Autoprefixer relies on a library called 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 的库来指出需要为哪些浏览器加前缀。 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:

你可以为 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:

或者你也可以在项目目录下添加一个新文件 .browserslistrc，用于指定你要支持哪些浏览器：
```
 ### Supported Browsers
 > 1%
 last 2 versions
```

See the browserslist repo for more examples of how to target specific browsers and versions.

参见 browserslist 的代码库以得到如何指定浏览器及其版本的更多例子。

Backward compatibility

向后兼容

If you want to produce a progressive web app and are using Lighthouse to grade the project, add the following browserslist entry to your package.json file, in order to eliminate the old flexbox prefixes:

如果你要制作渐进式应用，并使用 Lighthouse 来对该项目进行评分，请为 package.json 添加如下的 browserslist 条目，以消除老版本的 flexbox 前缀：

"browserslist": [
  "last 2 versions",
  "not ie <= 10",
  "not ie_mob <= 10"
]

{@a proxy}

Proxying to a backend server

代理到后端服务器

You can use the proxying support 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 开发服务器中的代理支持来把特定的 URL 转发给后端服务器，只要传入 --proxy-config 选项就可以了。比如，要把所有到 http://localhost:4200/api 的调用都转给运行在 http://localhost:3000/api 上的服务器，可采取如下步骤。

Create a file proxy.conf.json in the projects src/ folder, next to package.json.

在项目的 src/ 目录下创建一个 proxy.conf.json 文件，紧挨着 package.json。
Add the following content to the new proxy file:

往这个新的代理配置文件中添加如下内容：
```
{
  "/api": {
    "target": "http://localhost:3000",
    "secure": false
  }
}
```

In the CLI configuration file, angular.json, add the proxyConfig option to the serve target:

在 CLI 配置文件 angular.json 中为 serve 目标添加 proxyConfig 选项：

...
"architect": {
  "serve": {
    "builder": "@angular-devkit/build-angular:dev-server",
    "options": {
      "browserTarget": "your-application-name:build",
      "proxyConfig": "src/proxy.conf.json"
    },
...

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.

你可以编辑这个代理配置文件，以添加配置项，例子如下。要查看所有选项的详细说明，参见 webpack DevServer 文档。

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": {
    "target": "http://localhost:3000",
    "secure": false,
    "pathRewrite": {
      "^/api": ""
    }
  }
}

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

如果你要访问的后端不在 localhost 上，还要设置 changeOrigin 选项。比如：

{
  "/api": {
    "target": "http://npmjs.org",
    "secure": false,
    "pathRewrite": {
      "^/api": ""
    },
    "changeOrigin": true
  }
}

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

要想了解你的代理是否在如预期般工作，可以设置 logLevel 选项。比如：

{
  "/api": {
    "target": "http://localhost:3000",
    "secure": false,
    "pathRewrite": {
      "^/api": ""
    },
    "logLevel": "debug"
  }
}

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 = [
    {
        context: [
            "/my",
            "/many",
            "/endpoints",
            "/i",
            "/need",
            "/to",
            "/proxy"
        ],
        target: "http://localhost:3000",
        secure: false
    }
]

module.exports = PROXY_CONFIG;

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

在 CLI 配置文件 angular.json 中，指向 JavaScript 配置文件：

...
"architect": {
  "serve": {
    "builder": "@angular-devkit/build-angular:dev-server",
    "options": {
      "browserTarget": "your-application-name:build",
      "proxyConfig": "src/proxy.conf.js"
    },
...

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": {
        "target": "http://localhost:3000",
        "secure": false,
        "bypass": function (req, res, proxyOptions) {
            if (req.headers.accept.indexOf("html") !== -1) {
                console.log("Skipping proxy for browser request.");
                return "/index.html";
            }
            req.headers["X-Custom-Header"] = "yes";
        }
    }
}

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 通过你的公司代理转发此调用：

npm install --save-dev https-proxy-agent

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 = [{
  context: '/api',
  target: 'http://your-remote-server.com:3000',
  secure: false
}];

function setupForCorporateProxy(proxyConfig) {
  var proxyServer = process.env.http_proxy || process.env.HTTP_PROXY;
  if (proxyServer) {
    var agent = new HttpsProxyAgent(proxyServer);
    console.log('Using corporate proxy server: ' + proxyServer);
    proxyConfig.forEach(function(entry) {
      entry.agent = agent;
    });
  }
  return proxyConfig;
}

module.exports = setupForCorporateProxy(proxyConfig);

24 KiB Raw Blame History Unescape Escape