Layui upload 的 headers 必须在 upload.render() 初始化时传入,不支持后续动态修改;正确方式是将 headers 设为函数,每次上传前动态返回最新请求头(如从 localStorage 读取 token),并确保服务端 CORS 配置允许对应 header。

layui upload 的 headers 配置必须在 upload.render() 时传入
layui 的 upload 模块不支持上传中途动态修改请求头,headers 只能在初始化时通过配置对象传入。如果你在调用 upload.render() 后试图修改实例的 config.headers,它不会生效——因为实际请求是由内部 XMLHttpRequest 发起的,而 headers 是在每次请求前从初始 config 中读取的。
常见错误是写成这样(无效):
var uploadInst = upload.render({ url: '/api/upload' });
uploadInst.config.headers = { 'Authorization': 'Bearer ' + token }; // ❌ 不会起作用
正确做法是把 headers 作为顶层配置项传进去:
-
headers必须是对象,键名区分大小写,比如'Authorization'不能写成'authorization' - 值可以是字符串或函数;若为函数,会在每次请求前执行,适合处理动态 token(如 localStorage 里取)
- 函数形式更安全,避免初始化时 token 还没拿到导致 header 缺失
用函数返回 headers 能解决 token 异步获取问题
登录后 token 往往存在 localStorage 或由异步接口返回,直接写死字符串容易出错。把 headers 设为函数,能确保每次请求都取到最新值:
upload.render({
elem: '#uploadDemo',
url: '/api/upload',
headers: function(){
var token = localStorage.getItem('access_token');
return {
'Authorization': 'Bearer ' + (token || ''),
'X-Request-ID': 'upload-' + Date.now()
};
},
done: function(res){
console.log('上传成功', res);
}
});
注意:headers 函数在每次选择文件并触发上传时都会执行,所以即使 token 后续刷新了(比如过期重登),下一次上传也会自动带上新值。
- 函数内不要做耗时操作(如发请求),否则会阻塞上传发起
- 如果 token 为空,建议仍返回对象(哪怕 Authorization 值为空字符串),避免因返回
undefined导致请求头被忽略 - 某些后端校验严格,空 Authorization 可能被拒绝,此时可在函数里加兜底逻辑(如跳转登录)
服务端接收不到自定义 header?检查 CORS 配置
加了 Authorization 或其他自定义 header 后,浏览器会自动发出预检请求(OPTIONS),如果服务端没正确响应,上传会直接失败,控制台报错类似:Failed to load http://xxx: Error: Header Authorization is not allowed by Access-Control-Allow-Headers。
这是典型的跨域 header 白名单问题,需服务端明确允许:
- 响应头中必须包含
Access-Control-Allow-Headers: Authorization, X-Request-ID(列出你实际用到的自定义 header) - 同时要带
Access-Control-Allow-Credentials: true(如果前端带 cookie) - 注意:
Access-Control-Allow-Origin不能为*,当存在 credentials 或自定义 header 时,必须指定具体域名
Node.js(Express)示例:
app.use((req, res, next) => {
res.header('Access-Control-Allow-Origin', 'http://localhost:8080');
res.header('Access-Control-Allow-Headers', 'Authorization, X-Request-ID, Content-Type');
res.header('Access-Control-Allow-Credentials', 'true');
next();
});
layui 2.8+ 的 auto 模式下 headers 生效逻辑不变
无论 auto: true(选完自动上传)还是 auto: false(点击按钮才上传),headers 都只在真正发起 XHR 请求时注入。但要注意一个边界情况:如果用了 bindAction 自定义上传触发元素,headers 依然从原始 render 配置中读取,不会继承 bindAction 元素所在作用域的变量。
- 也就是说,不要指望在
bindAction的 click 回调里改headers—— 它不生效 - 如果需要根据不同按钮携带不同 header,应为每个上传实例单独
render,而不是复用同一个实例 - layui 不支持单实例多 header 切换,这是设计限制,不是 bug
header 设置看着简单,但 token 时效性、CORS 白名单、实例生命周期这三块最容易漏掉。尤其是开发环境常绕过跨域(比如用 proxy),上线后突然 403 或预检失败,问题就出在这里。











