close
  • 简体中文

      • server.proxy

      • 类型：
      type ProxyConfig =
  | Record<string, string | ProxyOptions>
  | ProxyOptions[]
  | ProxyOptions;
      • 默认值： undefined

      为开发服务器或预览服务器配置代理规则，将请求代理到指定的服务上。

      示例

      基础用法

      rsbuild.config.ts
      export default {
  server: {
    proxy: {
      // http://localhost:3000/api -> http://localhost:3000/api
      // http://localhost:3000/api/foo -> http://localhost:3000/api/foo
      '/api': 'http://localhost:3000',
    },
  },
};

      此时，/api/users 请求将会代理到 http://localhost:3000/api/users。

      你也可以代理到线上域名，比如:

      rsbuild.config.ts
      export default {
  server: {
    proxy: {
      // http://localhost:3000/api -> https://nodejs.org/api
      // http://localhost:3000/api/foo -> https://nodejs.org/api/foo
      '/api': 'https://nodejs.org',
    },
  },
};

      重写路径

      如果你不想传递 /api，可以通过 pathRewrite 重写请求路径：

      rsbuild.config.ts
      export default {
  server: {
    proxy: {
      // http://localhost:3000/api -> http://localhost:3000
      // http://localhost:3000/api/foo -> http://localhost:3000/foo
      '/api': {
        target: 'http://localhost:3000',
        pathRewrite: { '^/api': '' },
      },
    },
  },
};

      代理 WebSocket 请求

      如果你希望代理 WebSocket 请求，可以通过 ws 开启：

      rsbuild.config.ts
      export default {
  server: {
    proxy: {
      '/rsbuild-hmr': {
        target: 'http://localhost:3000', // 将会代理到 ws://localhost:3000/rsbuild-hmr
        ws: true,
      },
    },
  },
};

      选项

      Rsbuild server proxy 基于 http-proxy-middleware 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。

      Rsbuild server proxy 完整类型定义为：

      import type { Options as HttpProxyOptions } from 'http-proxy-middleware';

type Filter = string | string[] | ((pathname: string, req: Request) => boolean);

type ProxyOptions = HttpProxyOptions & {
  bypass?: (
    req: IncomingMessage,
    res: ServerResponse,
    proxyOptions: ProxyOptions,
  ) => MaybePromise<string | undefined | null | boolean>;
  context?: Filter;
};

type ProxyConfig =
  | ProxyOptions
  | ProxyOptions[]
  | Record<string, string>
  | Record<string, ProxyOptions>;

      除了 http-proxy-middleware 的选项外，Rsbuild 还支持 bypass 和 context 两个选项。

      bypass

      一些情况下，你可能不想代理所有请求。可以通过 bypass 函数来绕过代理。

      在函数中，你可以访问到 request、response 和 proxy 选项。

      • 返回 null 或 undefined 会继续用代理处理请求。
      • 返回 true 会跳过代理继续处理请求。
      • 返回 false 会返回 404 错误。
      • 返回一个具体的服务路径，将会使用此路径替代原请求路径。
      • 返回一个 Promise，可以异步处理请求。

      例如，你可能希望对浏览器请求返回 HTML 页面，而对 API 请求则进行代理转发。你可以这样配置：

      rsbuild.config.ts
      export default {
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        bypass(req, res, proxyOptions) {
          if (req.headers.accept.indexOf('html') !== -1) {
            console.log('Skipping proxy for browser request.');
            return '/index.html';
          }
        },
      },
    },
  },
};

      context

      用于代理多个指定的路径到同一个目标。

      rsbuild.config.ts
      export default {
  server: {
    proxy: [
      {
        context: ['/auth', '/api'],
        target: 'http://localhost:3000',
      },
    ],
  },
};