NextJS中Axios请求拦截器无法添加userId请求头的问题

核心原因 #

这种情况大概率是浏览器的CORS安全机制导致的：当自定义请求头（如userId）跨域发送时，浏览器会先发送OPTIONS预请求，询问后端是否允许该自定义头。如果后端没有明确在CORS响应中返回Access-Control-Allow-Headers: userId，浏览器会自动移除实际请求中的这个头，导致后端无法获取。

同时也需要排查Axios实例配置的细节问题，以下是具体解决方案：

解决方案1：修正FastAPI的CORS配置 #

在FastAPI中配置CORSMiddleware时，必须将自定义的userId头添加到allow_headers列表中，示例代码：

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

app = FastAPI()

origins = [
    "http://localhost:3000",  # 你的NextJS前端地址
    # 其他需要允许的源
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,  # 若请求需携带Cookie等凭证则开启
    allow_methods=["*"],
    allow_headers=["userId", "Content-Type"],  # 明确列出自定义头，避免用*（带凭证场景下*不生效）
)

解决方案2：检查Axios实例的拦截器配置 #

确认Axios请求拦截器正确挂载，且未被后续配置覆盖。示例正确的Axios实例配置：

// utils/axios.js
import axios from 'axios';

const axiosInstance = axios.create({
  baseURL: 'http://your-fastapi-server-url',
  withCredentials: true,  // 跨域带凭证时需开启
});

axiosInstance.interceptors.request.use(
  (config) => {
    // 确保userId存在再添加请求头
    const userId = localStorage.getItem('userId'); // 或从其他前端存储/状态中获取
    if (userId) {
      config.headers['userId'] = userId;
    }
    return config;
  },
  (error) => Promise.reject(error)
);

export default axiosInstance;

检查要点：

• 拦截器需在实例创建后立即添加，避免被其他代码覆盖config.headers
• 确认在客户端环境中能正确获取到userId（如避免在SSR场景下依赖浏览器的localStorage）

解决方案3：处理NextJS的SSR/SSG场景差异 #

如果请求在服务器端渲染（如getServerSideProps）时发送，Axios运行在Node.js环境，不会触发浏览器CORS预请求，但需确保userId能从服务端上下文获取（如Cookie、Session），而非依赖浏览器存储：

// pages/some-page.js
import axiosInstance from '../utils/axios';

export async function getServerSideProps(context) {
  // 从服务端请求上下文获取userId
  const userId = context.req.cookies.userId;
  try {
    const res = await axiosInstance.get('/api/data', {
      headers: { userId }
    });
    return { props: { data: res.data } };
  } catch (err) {
    return { props: { data: null } };
  }
}

验证步骤 #

1. 修改FastAPI的CORS配置后重启后端服务
2. 在浏览器开发者工具的Network面板中，查看实际POST请求的Request Headers，确认userId是否存在
3. 若仍不存在，在Axios拦截器中添加console.log(config.headers)，验证请求头是否被正确设置

内容的提问来源于stack exchange，提问作者shijie xu