当前位置：首页 > news >正文

Nuxt 3 跨域问题完整解决方案（开发 + 生产环境）

news 2025/8/15 11:09:11

开发环境解决方案（Localhost）

使用 Nitro 开发代理解决跨域：

配置 nuxt.config.ts:

export default defineNuxtConfig({nitro: {devProxy: {'/api': {target: 'https://your-api.com/api',changeOrigin: true, // 解决跨域关键配置secure: false,     // HTTPS校验禁用headers: {// 可添加自定义头部'X-Custom-Header': 'value'}// pathRewrite: { '^/api': '' } // 可选：路径重写}}},runtimeConfig: {public: {apiBase: '/api' // 客户端统一使用的API前缀}}
})

在组件中使用：

<script setup>
// 使用统一前缀发起请求
const { data } = await useFetch('/api/users', {headers: { 'Authorization': 'Bearer xxx' }
})
</script>

验证代理是否生效：

# 启动开发服务器
npm run dev# 浏览器访问
http://localhost:3000/api/test → 实际请求 https://your-api.com/api/test

生产环境解决方案

方案一：Nitro 中间件代理 (Node 环境适用)

创建服务端中间件：

// ~/server/middleware/proxy.ts
import { createProxyMiddleware } from 'http-proxy-middleware'export default defineEventHandler((event) => {const proxy = createProxyMiddleware('/api', {target: 'https://your-api.com',changeOrigin: true,pathRewrite: { '^/api': '/api' },secure: true})return new Promise((resolve, reject) => {proxy(event.node.req, event.node.res, (err) => {if (err) reject(err)else resolve()})})
})

安装依赖：

npm install http-proxy-middleware

方案二：Nginx 反向代理 (推荐生产使用)

修改 Nginx 配置：

server {listen 80;server_name your-domain.com;# 前端资源服务location / {proxy_pass http://localhost:3000; # Nuxt服务器proxy_http_version 1.1;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection 'upgrade';proxy_set_header Host $host;}# API代理location /api/ {proxy_pass https://your-api.com/api/;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;# CORS headers (如果需要暴露给浏览器)add_header 'Access-Control-Allow-Origin' '*' always;add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;}
}

方案三：CORS 配置（当控制后端时）

在后端添加 CORS 头：

// Node.js 示例
app.use((req, res, next) => {res.setHeader('Access-Control-Allow-Origin', '*')res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE')res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')next()
})

环境差异处理

开发环境特殊处理:

// ~/composables/useApi.ts
export default function() {const config = useRuntimeConfig()// 开发环境使用代理前缀，生产环境用完整URLconst baseURL = import.meta.dev ? config.public.apiBase : 'https://your-api.com/api'return {fetchData: (url: string) => useFetch(url, { baseURL })}
}

统一客户端调用:

<script setup>
import useApi from '~/composables/useApi'const { fetchData } = useApi()const getUser = async () => {const { data } = await fetchData('/users')return data
}
</script>

生产环境部署流程

基于 Nginx 的部署架构：

客户端浏览器 → Nginx (80端口)├─ /     → Nuxt 服务器└─ /api  → 后端API服务器

注意事项:

HTTPS 生产环境必须启用
设置合理的超时配置（proxy_connect_timeout, proxy_read_timeout）
在云平台（AWS/Cloudflare）可配置网关路由替代 Nginx
静态站点部署（SSG）无法使用服务端代理，需直接配置 CORS

验证流程

开发环境验证：

curl http://localhost:3000/api/ping
# 应返回API服务器响应而非Nuxt默认404

生产环境验证：

# 测试Nginx代理
curl -I https://your-domain.com/api/status# 检查响应头应包含：
access-control-allow-origin: *
x-proxied-by: nginx

浏览器端验证：

// Chrome开发者工具Console
fetch('/api/test').then(res => console.log(res.headers))

故障排查清单

开发环境代理失效:
- 检查nuxt.config.ts是否配置正确
- 确保未禁用 nitro：devServer: { watch: [] }会导致代理失效
- 重启开发服务器

生产环境 502 错误:

# 在nginx配置中添加调试信息
location /api {proxy_set_header X-Debug-Proxy-Pass $proxy_pass;add_header X-Backend-Address $proxy_host always;
}

CORS 预检失败：
- 确保 OPTIONS 请求被正确处理
- 验证响应头包含：access-control-allow-methods, access-control-allow-headers
HTTPS 混合内容问题:
- 前端 HTTPS 必须代理到 HTTPS 后端
- 如后端仅 HTTP，需设置：proxy_ssl_verify off