FastAPI + Vite 联调踩坑实录：CORS、IPv6、路由参数

前后端联调时，明明代码逻辑没问题，但就是调不通。CORS报错、IPv6解析失败、路由参数丢失——这三个坑花了我一个下午。

坑1：CORS跨域——前端调后端报错

前端Vite项目调FastAPI后端，浏览器报错：

text

Access to XMLHttpRequest at 'http://localhost:8000/api/xxx' 
from origin 'http://localhost:5173' has been blocked by CORS policy

根本原因：

FastAPI默认只允许同源请求。前端跑在5173端口，后端跑在8000端口，不同源，被浏览器拦截。

解决方案：在FastAPI配置CORSMiddleware

python

from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:5173",  # Vite默认端口
        "http://127.0.0.1:5173",
        "http://47.101.64.58",    # 部署后的前端地址
        "http://47.101.64.58:8080",
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

开发时的快捷方案：

python

# 开发环境允许所有来源（上线前记得改）
if os.getenv("ENV") == "development":
    app.add_middleware(
        CORSMiddleware,
        allow_origins=["*"],
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )

坑2：前端代理指向IPv6——ECONNREFUSED ::1:8000

Vite配置了代理，但请求一直报错：

text

ECONNREFUSED ::1:8000

根本原因：

Vite代理配置target: "http://localhost:8000"时，在某些环境下Node.js会优先解析到IPv6地址（::1），但后端只监听了IPv4（127.0.0.1）。

解决方案：

javascript

// vite.config.js
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://127.0.0.1:8000',  // 直接用127.0.0.1，不用localhost
        changeOrigin: true,
      }
    }
  }
})

或者让FastAPI同时监听IPv4和IPv6：

bash

uvicorn main:app --host 0.0.0.0 --port 8000

坑3：会议ID丢失——切页面后提示"缺少meeting_id"

从会议列表点进详情页，页面加载正常。刷新后，提示"缺少会议ID"。

根本原因：

路由跳转时没带meeting_id参数，或者用的是state传递（刷新后丢失）。

解决方案：统一用query参数

javascript

// ❌ 错误：用state传递（刷新丢失）
navigate('/smart-summary', { state: { meetingId: 123 } });

// ✅ 正确：用query参数传递（刷新保留）
navigate('/smart-summary?meeting_id=123');

// 组件中获取
const [searchParams] = useSearchParams();
const meetingId = searchParams.get('meeting_id');

踩坑总结：

• CORS是前后端分离项目最常见的坑，开发阶段可以放宽限制，上线前收窄。

• Vite代理的localhost解析问题，直接换127.0.0.1省心。

• 页面间传递关键参数用query，不要用state——刷新页面是用户常见操作，不能因此丢失数据。