【笔记】Ant Design（含Umi Max）+FastAPI 内网部署&接口代理 核心笔记

一、前端项目启动方式（开发/打包后）

1. 开发环境启动（npm run start）

• 默认端口：8001，修改方式（避坑：无需在config.ts加port，用命令行/script配置）：

方式1：启动时临时指定端口（单次生效）

npm run start -- --port 8080

方式2：package.json配置永久端口（推荐，无报错）

打开项目根目录package.json，修改scripts启动命令：

{ 
    "scripts": 
        { "start": "umi dev --port 8080", // 固定开发端口8080，永久生效 
          "start:test": "umi dev --mode test --port 8080", // test环境同步改 
          "build": "umi build"
        }
}

• 核心特性：自带Umi开发服务器，支持proxy.ts代理转发，仅开发环境生效（Ant Design集成Umi Max的默认能力）。

2. 打包后静态服务启动（npm run build 生成dist后）

方式1：Python内置http.server（仅预览纯静态页面，避坑！）

• 命令：cd dist && python -m http.server 8080 --bind 0.0.0.0

• 缺点：仅支持GET/HEAD请求，不支持POST/PUT，接口直接报501错误，禁止用于带接口的项目。

方式2：serve工具（前端专用，高版本兼容问题）

• 安装：npm install -g serve

• 正确命令（项目根目录，高版本需加http协议）：serve -s dist -l http://0.0.0.0:8080

• 特性：支持所有HTTP请求方法，适配单页应用路由（-s参数），但高版本（Node.js24+）易出协议解析报错，可替换为anywhere。

方式3：anywhere工具（推荐，无兼容问题，支持代理）

• 安装：npm install -g anywhere

• 核心启动命令（项目根目录，托管dist+允许内网访问）：

anywhere -p 8080 -d dist -h 0.0.0.0

• 参数说明：-p指定端口，-d指定静态文件目录，-h 0.0.0.0绑定所有网卡，内网设备可访问。

• 特性：支持POST/GET等所有请求，可配置代理转发，Windows/高版本Node.js兼容良好（适配Ant Design打包后的静态文件）。

二、接口代理配置（开发/打包后，核心避坑）

核心前提：代理仅为「中间服务转发」，浏览器端始终是「前端IP+端口」的同源请求

1. 开发环境代理（proxy.ts，项目根目录，Ant Design集成Umi Max默认支持）

• 作用：Umi开发服务器转发，避免开发时跨域，仅npm run start生效，打包后失效。

• 示例配置（转发/api请求到FastAPI）：

module.exports = {
  dev: { // 开发环境代理节点（npm run start对应）
    '/api/': {
      target: 'http://localhost:8003', // 后端地址
      changeOrigin: true, // 修改Origin头，避免跨域
      pathRewrite: false // 路径一致（前端/api/xxx → 后端/api/xxx），无需重写
    }
  },
  test: { // 可选：test环境代理（npm run start:test对应）
    '/api/': {
      target: 'http://localhost:8003',
      changeOrigin: true
    }
  }
};

• 配合：前端src/app.ts中baseURL: undefined，让请求走代理（避免baseURL优先级压制代理）。

2. 打包后anywhere代理（proxy.config.js，项目根目录，文件名/路径固定）

• 作用：anywhere静态服务转发，打包后替代Umi代理，需和anywhere启动配合。

• 示例配置：

module.exports = {
  '/api': {
    target: 'http://localhost:8003', // 后端地址（内网部署写后端局域网IP）
    changeOrigin: true, // 关键：修改请求Origin，让后端认为同源
    secure: false, // 内网部署关闭HTTPS校验，避免证书报错
    methods: ['GET', 'POST', 'PUT', 'DELETE'] // 允许所有请求方法
  }
};

• 生效：配置后重启anywhere服务，终端会打印代理转发日志（如[proxy] /api/login → 后端地址）。

• 避坑：Windows路径含空格（如「登录界面」）可能导致配置未识别，优先用「baseURL+后端CORS」方案。

3. 代理失效常见原因

1. 前端baseURL有值，请求直接跳过代理，需设为undefined；

2. 配置文件路径/文件名错误（anywhere的proxy.config.js必须在项目根目录，大小写/后缀不能错）；

3. 未重启代理服务（修改配置后需重启前端/anywhere）；

4. Windows路径含特殊字符/空格，导致配置未识别；

5. Ant Design的Umi代理节点与启动命令不匹配（如dev节点需对应npm run start）。

三、Ant Design+FastAPI 内网部署最终方案（推荐：baseURL+后端CORS，零代理坑）

核心思路：抛弃前端代理，前端直接请求后端，后端配置CORS允许指定内网网段，简单稳定无兼容问题（适配Ant Design打包后部署）

步骤1：前端配置baseURL（src/app.ts，关键：写后端「局域网IP+端口」）

• 作用：打包后前端请求直接发往后端，无需中间代理，内网设备可访问。

• 示例配置（后端IP：[192.168.66.39](192.168.66.39)，端口8003）：

import type { RequestConfig } from '@umijs/max'; // Ant Design集成Umi Max的类型
export const request: RequestConfig = {
  baseURL: 'http://192.168.66.39:8003', // 后端局域网IP+端口，禁止写localhost
  withCredentials: true, // 允许携带cookie/令牌，必须保留（配合后端CORS）
  timeout: 10000 // 可选：超时时间
};

• 生效：修改后必须重新打包 （npm run build），让dist文件中的代码生效。

步骤2：后端FastAPI配置CORS（网段白名单，仅允许指定内网访问）

核心修正：FastAPI正则匹配网段用allow_origin_regex（单个字符串，多网段|分隔）

• 错误原因：之前用allow_origins写正则列表，框架抛出TypeError（该参数仅支持普通字符串）。

• 最终可用配置（适配192.168.66.*网段+本机调试）：

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# CORS网段白名单：仅允许指定内网访问，解决跨域+保证安全性
app.add_middleware(
    CORSMiddleware,
    allow_origin_regex=r"http://(192.168.66.\d+|127.0.0.1|localhost):\d+",
    allow_credentials=True, # 与前端withCredentials对应，必须为True
    allow_methods=["*"],     # 允许所有请求方法（GET/POST等）
    allow_headers=["*"]      # 允许所有请求头
)

# 示例接口（与前端/api路径对应）
@app.post("/api/login/account")
async def login(username: str, password: str):
    return {"code": 200, "message": "登录成功", "data": {"username": username}}

@app.get("/api/currentUser")
async def get_current_user():
    return {"code": 200, "data": {"username": "admin", "roles": ["admin"]}}

• 扩展多网段：括号内用|追加，示例（允许192.168.66.+192.168.0.）：

allow_origin_regex=r"http://(192.168.66.\d+|192.168.0.\d+|127.0.0.1|localhost):\d+",

• 生效：修改后必须重启后端服务 （如uvicorn main:app --host 0.0.0.0 --port 8003）。

步骤3：前端打包后启动（anywhere，仅托管静态文件）

• 命令：项目根目录执行anywhere -p 8080 -d dist -h 0.0.0.0

• 无需配置代理，前端请求通过baseURL直接发往后端（Ant Design静态文件正常加载，接口请求无跨域）。

步骤4：内网访问方式

• 内网设备浏览器输入：http://前端服务器局域网IP:8080（如[192.168.66.39:8080](192.168.66.39:8080)）。

• 验证请求链路：浏览器F12→Network，请求URL应为http://后端IP:8003/api/xxx（如[192.168.66.39:8003/api/login/account](192.168.66.39:8003/api/login/account)），而非前端IP。

四、常见错误及解决方案

1. 开发环境改port报错（config.ts加port失败）

• 原因：Ant Design集成的Umi Max可能存在配置冲突，或版本不支持直接在config.ts加port。

• 解决：改用package.json的scripts命令配置端口（永久生效，无报错），参考「开发环境启动」部分。

2. 501 Unsupported method ('POST')

• 原因：使用Python内置http.server启动，不支持POST请求。

• 解决：替换为anywhere/serve工具。

3. serve报错 Unknown --listen endpoint scheme

• 原因：高版本serve要求-l参数带http协议，或Node.js版本兼容问题。

• 解决：加协议serve -s dist -l http://0.0.0.0:8080，或直接换anywhere。

4. 404/405 接口错误

• 原因：前端代理未触发，请求发往前端静态服务（无/api接口）；或baseURL配置错误（写localhost而非局域网IP）。

• 解决：改用「baseURL+后端CORS」方案，确保baseURL是后端局域网IP。

5. FastAPI CORS 报TypeError: first argument must be string or compiled pattern

• 原因：混淆CORS参数，在allow_origins（普通列表）中写正则。

• 解决：用allow_origin_regex（单个字符串）配置正则，多网段|分隔。

6. 跨域CORS报错

• 原因：后端CORS未允许前端来源，或allow_credentials前后端不一致。

• 解决：检查后端CORS正则是否匹配前端网段，确保前后端withCredentials/allow_credentials均为True。

五、关键部署避坑点

1. 所有内网访问的IP，禁止写 localhost/127.0.0.1，必须写「局域网IP」（如[192.168.66.39](192.168.66.39)），否则仅本机可访问；

2. 前端修改baseURL/代理配置后，必须重新打包 （npm run build），否则旧代码生效；

3. 后端修改CORS/接口后，必须重启服务，否则配置不生效；

4. 启动静态服务时，必须加-h 0.0.0.0（anywhere）/--bind 0.0.0.0（Python），否则内网设备无法访问；

5. 内网部署优先用「baseURL+后端CORS」，避开所有前端代理的兼容/配置坑（Ant Design+FastAPI最佳实践）；

6. Ant Design集成Umi Max的代理仅开发环境生效，打包后需用静态服务代理或直接请求后端，不可依赖Umi代理。