配置 Web 开发配置文件

Flutter Web 包含开发服务器，默认在 localhost 域通过 HTTP 在随机分配的端口上提供应用。命令行参数可快速修改服务器行为，本文档侧重更结构化的方式：通过集中的 web_dev_config.yaml 文件定义服务器行为。该配置文件可自定义主机、端口、HTTPS 设置与代理规则，确保开发环境一致。

在 Flutter 项目根目录添加 web_dev_config.yaml 文件。若尚未创建 Flutter 项目，请参阅使用 Flutter 构建 Web 应用入门。

你可以为开发服务器定义主机、端口与 HTTPS 设置。

server:
  host: "0.0.0.0" # Defines the binding address <string>
  port: 8080 # Specifies the port <int> for the development server
  https:
    cert-path: "/path/to/cert.pem" # Path <string> to your TLS certificate
    cert-key-path: "/path/to/key.pem" # Path <string> to TLS certificate key

你还可以向开发服务器的响应注入自定义 HTTP 标头。

server:
  headers:
    - name: "X-Custom-Header" # Name <string> of the HTTP header
      value: "MyValue" # Value <string> of the HTTP header
    - name: "Cache-Control"
      value: "no-cache, no-store, must-revalidate"

请求按 web_dev_config.yaml 文件中的顺序进行匹配。

使用 prefix 字段进行简单路径前缀匹配。

server:
  proxy:
    - target: "http://localhost:5000/" # Base URL <string> of your backend
      prefix: "/users/" # Path <string>
    - target: "http://localhost:3000/"
      prefix: "/data/"
      replace: "/report/" # Replacement <string> of path in redirected URL (optional)
    - target: "http://localhost:4000/"
      prefix: "/products/"
      replace: ""

说明：

• 对 /users/names 的请求会转发到 http://localhost:5000/users/names。

• 对 /data/2023/ 的请求会转发到 http://localhost:3000/report/2023，因为 replace: "/report/" 会替换 /data/ 前缀。

• 对 /products/item/123 的请求会转发到 http://localhost:4000/item/123，因为 replace: "" 会用空字符串替换 /products/ 前缀从而将其移除。

你还可以使用 regex 字段进行更灵活、复杂的匹配。

server:
  proxy:
    - target: "http://localhost:5000/"
      regex: "/users/(\d+)/$" # Path <string> matches requests like /users/123/
    - target: "http://localhost:4000/"
      regex: "^/api/(v\d+)/(.*)" # Matches requests like /api/v1/users
      replace: "/$2?apiVersion=$1" # Allows capture groups (optional)

说明：

• 对 /users/123/ 的请求完全匹配第一条规则，因此转发到 http://localhost:5000/users/123/。

• 对 /api/v1/users/profile/ 的请求匹配第二条规则，因此转发到 http://localhost:4000/users/profile/?apiVersion=v1。

请记住设置的优先级顺序：

1. 命令行参数（如 --web-hostname、--web-port）

2. web_dev_config.yaml 中的设置

3. 内置默认值