本文详解在 Vue（Vite，端口 5173）与 Express（端口 3000）分离部署的开发环境下，因跨域导致 httpOnly Cookie 无法发送/接收的问题，并提供开发期代理与生产期反向代理的完整解决方案。
本文详解在 vue（vite，端口 5173）与 express（端口 3000）分离部署的开发环境下，因跨域导致 `httponly` cookie 无法发送/接收的问题，并提供开发期代理与生产期反向代理的完整解决方案。
在全栈开发中，前端 Vue（通常通过 Vite 启动于 http://localhost:5173）与后端 Express（运行于 http://localhost:3000）分属不同源，浏览器出于安全策略会阻止跨域请求携带凭据（如 httpOnly Cookie），导致登录态无法透传——即使后端已正确设置 Set-Cookie，前端发起的 fetch 或 axios 请求也不会自动带上该 Cookie，认证流程因此中断。
✅ 开发阶段：使用 Vite 代理（推荐且标准做法）
Vite 内置开发服务器支持 server.proxy 配置，可将前端 /api 请求透明转发至 Express 后端，实现「同源」假象，从而让 Cookie 正常收发。在 vite.config.ts 中配置如下：
// vite.config.ts
export default defineConfig({
server: {
proxy: {
'/api': {
target: 'http://localhost:3000',
changeOrigin: true, // 修改请求头 Origin，避免后端校验失败
secure: false, // 若 Express 使用 HTTPS 开发环境则设为 true
cookies: { // 确保 Cookie 转发（Vite ≥ 4.3 默认启用，但显式声明更清晰）
sameSite: 'lax', // 推荐设为 'lax' 或 'strict'，兼容主流浏览器
}
}
}
}
})配置后，前端所有对 /api/login、/api/user 的请求将被代理至 http://localhost:3000/api/...，浏览器认为这是同一源请求，httpOnly Cookie 可被自动携带与存储。
⚠️ 注意事项：
- Express 后端需明确设置响应头以支持凭据传递：
// Express 中（如 app.ts） app.use((req, res, next) => { res.header('Access-Control-Allow-Credentials', 'true'); res.header('Access-Control-Allow-Origin', 'http://localhost:5173'); // 必须指定具体源，不可用 '*' res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization'); next(); }); - 登录接口（如
POST /api/login）返回 Cookie 时，务必设置SameSite: 'Lax'（开发环境兼容性最佳）及HttpOnly: true、Secure: false（开发用 HTTP）：res.cookie('auth_token', token, { httpOnly: true, secure: false, // 开发环境禁用 HTTPS 时必须为 false sameSite: 'lax', // 关键：允许跨站 GET（如导航）携带，但阻止 POST 跨站提交（防 CSRF） maxAge: 24 * 60 * 60 * 1000 });
✅ 生产阶段：Nginx 反向代理（统一域名，彻底规避跨域）
构建 Vue 项目（npm run build）后，将 dist/ 目录与 Express 应用一同部署于 Nginx，通过路径区分前后端流量：
# nginx.conf
server {
listen 80;
server_name example.com;
# 前端静态资源
location / {
root /var/www/my-app/dist;
try_files $uri $uri/ /index.html;
}
# API 请求反向代理至 Express
location /api/ {
proxy_pass http://127.0.0.1:3000/; # 注意末尾 '/'，确保路径重写正确
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 关键：透传 Cookie
proxy_cookie_path / "/";
}
}此时，https://example.com/ 与 https://example.com/api/login 属于同源，浏览器原生支持 httpOnly Cookie 的读写与自动携带，无需任何前端适配。
立即学习“前端免费学习笔记（深入）”；
? 总结：
- ❌ 不要为开发便利而强行构建前端并用 Express
app.get('*')托管——这混淆了开发/生产职责，丧失热更新与调试能力； - ✅ 开发用 Vite Proxy（轻量、零额外服务、符合现代工具链）；
- ✅ 生产用 Nginx 反向代理（标准、安全、高性能）；
- ⚠️ 始终同步配置
SameSite、Secure、CORS 凭据头与 Cookie 属性，三者缺一不可。
