调用 API 时很多问题不是接口本身坏了而是请求头 Header 没配对。最常见的两个 Header 是Authorization告诉服务器“我是谁、有没有权限”Content-Type告诉服务器“我提交的 Body 是什么格式”如果这两个字段写错经常会遇到401 Unauthorized403 Forbidden415 Unsupported Media Type后端收不到参数Postman 能通浏览器代码不通这篇按实际配置流程讲清楚Header 写在哪里、Authorization怎么填、Content-Type怎么选以及在 Postman、Apifox、curl、fetch、Axios 里如何验证。1. 一个完整 API 请求长什么样先看一个典型的 POST JSON 请求POST /users HTTP/1.1 Host: api.example.com Authorization: Bearer YOUR_TOKEN Content-Type: application/json Accept: application/json {name:Tom,age:18}可以把它拆成三部分请求行POST /users HTTP/1.1 请求头Authorization、Content-Type、Accept 请求体{name:Tom,age:18}也就是说POST /users表示请求方法和接口路径Authorization、Content-Type、Accept是 Header最后一行 JSON 是 Body也就是提交的数据一个很重要的原则Header 放请求元信息不放业务参数。例如用户名、年龄、订单号通常放在 URL Query 或 BodyToken、Body 格式、期望返回格式通常放在 Header不要把业务 JSON 参数塞进 Header。2. Header 的基本写法HTTP Header 本质上是一组键值对Header-Name: Header Value常见写法Authorization: Bearer YOUR_TOKEN Content-Type: application/json Accept: application/json写 Header 时建议遵守这些规则Header 名通常不区分大小写但建议使用常见写法例如Content-Type、Authorization多个 Header 分多行写不要把多个 Header 硬拼成一行Header 是元信息不是 Body不要把 JSON 参数写到 Header 里以接口文档为准文档要求传X-API-Key就不要擅自改成Authorization不同工具中的位置如下工具Header 配置位置Postman / ApifoxHeaders表格curl-H参数JavaScript fetchheaders对象Axios请求配置里的headers环境变量方式代码里读取API_TOKEN、API_BASE_URL等变量后写入 Header3. Authorization 请求头怎么写Authorization用于鉴权。它的作用可以理解为告诉服务端当前请求是谁发起的是否有权限访问这个接口。最常见的写法是 Bearer TokenAuthorization: Bearer YOUR_TOKEN这里要注意几个细节Bearer和 token 中间必须有一个空格YOUR_TOKEN要替换成真实 token通常不要写成Bearer abc123除非文档明确要求带尖括号不要复制多余的引号、换行符、前后空格不要把 token 放到 URL 查询参数里错误示例Authorization: BearerYOUR_TOKEN问题Bearer后面缺少空格。错误示例Authorization: Bearer YOUR_TOKEN问题有些接口会把引号也当成 Header 值的一部分。推荐写法Authorization: Bearer abc1234. 常见鉴权 Header 类型不同平台的鉴权方式不完全一样并不是所有接口都使用Authorization: Bearer xxx。类型示例常见场景Bearer TokenAuthorization: Bearer xxxOAuth2、JWT、登录后访问接口Basic AuthAuthorization: Basic base64(username:password)简单账号密码认证、内部系统API Key HeaderX-API-Key: xxx开放平台、第三方 API签名认证Authorization: 签名结果云厂商 API、金融类 API有些接口文档可能要求X-API-Key: YOUR_API_KEY或者Token: YOUR_TOKEN这种情况下不要自行改成Authorization: Bearer YOUR_API_KEY除非文档明确支持。签名认证也要特别注意。某些云厂商或企业接口会把签名结果放到Authorization中但它和普通 Bearer Token 不是一回事。签名认证通常还会涉及时间戳请求路径请求方法Body 哈希Secret Key签名算法不能只复制一个 Header 就认为完成鉴权需要按对应接口文档生成签名。5. Content-Type 请求头怎么写Content-Type用来说明请求 Body 的格式。例如 Body 是 JSON{name:Tom,age:18}那么 Header 应该写Content-Type: application/json常见对应关系如下Body 类型Content-Type常见场景JSONapplication/jsonREST API 中常见的 POST / PUT表单键值对application/x-www-form-urlencoded登录表单、传统表单提交文件上传multipart/form-data上传图片、上传文件纯文本text/plain发送纯文本XMLapplication/xml或text/xml老系统、企业接口判断原则很简单Body 是什么格式Content-Type就写什么格式。例如你发送的是 JSON{name:Tom,age:18}就写Content-Type: application/json如果发送的是表单usernametompassword123456就写Content-Type: application/x-www-form-urlencoded不要 Body 是表单却写Content-Type: application/json否则后端可能解析不到参数。6. GET 请求需要 Content-Type 吗通常不需要。因为Content-Type描述的是请求 Body 的格式而 GET 请求一般没有 Body。例如GET /users?id1 HTTP/1.1 Host: api.example.com Authorization: Bearer YOUR_TOKEN这种请求通常不需要Content-Type: application/json很多新手会给所有请求都加上Content-Type: application/json大多数时候不一定直接报错但并不推荐。原因包括GET 通常没有 Body不需要声明 Body 格式某些接口会对多余 Header 做校验浏览器环境下某些 Header 可能触发 CORS 预检如果接口文档明确要求 GET 也传某个 Header则按文档来。7. Content-Type 和 Accept 的区别Content-Type和Accept很容易混淆。它们分别描述两个方向Content-Type: application/json Accept: application/json含义如下Header含义Content-Type我发给服务器的数据是什么格式Accept我希望服务器返回什么格式例如提交 JSON并希望服务端也返回 JSONContent-Type: application/json Accept: application/json如果接口没有特殊要求很多 API 不写Accept也会默认返回 JSON。但如果文档明确要求Accept: application/json建议按文档填写。8. Postman / Apifox 中如何配置 Header在 Postman 或 Apifox 中进入请求的Headers面板按 Key / Value 填写即可。示例KeyValueAuthorizationBearer YOUR_TOKENContent-Typeapplication/jsonAcceptapplication/json也可以写成文本理解Authorization: Bearer YOUR_TOKEN Content-Type: application/json Accept: application/json如果你在 Body 中选择了raw JSONPostman 通常会自动添加Content-Type: application/json如果你在 Authorization 面板选择了 Bearer Token也可能自动生成Authorization: Bearer xxx所以调试时要检查是否重复添加了两个Authorization是否重复添加了两个Content-Type是否还残留旧 tokentoken 前后是否有空格Header 名是否拼写错误Body 类型是否和Content-Type一致9. curl 中如何添加 Headercurl 使用-H添加请求头。示例POST JSON 请求curl -X POST https://api.example.com/users \ -H Authorization: Bearer YOUR_TOKEN \ -H Content-Type: application/json \ -d {name:Tom,age:18}说明-X POST指定请求方法-H添加 Header-d指定请求 BodyContent-Type要和-d的内容格式一致如果-d是 JSON 字符串-d {name:Tom,age:18}就使用Content-Type: application/json如果发送表单键值对curl -X POST https://api.example.com/login \ -H Content-Type: application/x-www-form-urlencoded \ -d usernametompassword123456就不要继续写Content-Type: application/json否则后端可能按 JSON 解析导致参数为空。10. JavaScript fetch 中如何配置 Headerfetch 中的 Header 写在headers对象里。示例fetch(https://api.example.com/users, { method: POST, headers: { Authorization: Bearer YOUR_TOKEN, Content-Type: application/json }, body: JSON.stringify({ name: Tom, age: 18 }) })重点有四个headers是对象JSON 请求要设置Content-Type: application/jsonBody 要用JSON.stringify()转成 JSON 字符串不要把 JavaScript 对象直接塞进body错误示例fetch(https://api.example.com/users, { method: POST, headers: { Content-Type: application/json }, body: { name: Tom, age: 18 } })问题在于body: { name: Tom, age: 18 }这里传的是 JavaScript 对象不是 JSON 字符串。推荐写法body: JSON.stringify({ name: Tom, age: 18 })另外不建议把生产环境 token 直接硬编码在前端源码里。11. Axios 中如何配置 HeaderAxios 的 Header 写在请求配置中。示例axios.post( https://api.example.com/users, { name: Tom, age: 18 }, { headers: { Authorization: Bearer YOUR_TOKEN, Content-Type: application/json } } )结构可以理解为axios.post(url, data, config)对应关系参数含义url请求地址data请求 Bodyconfig.headers请求头Axios 在发送普通对象时通常会按 JSON 处理并设置合适的Content-Type。不过新手阶段建议先显式写出来方便理解完整请求结构。真实项目中token 通常不会每个接口手写一遍而是通过请求拦截器统一添加。示例axios.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config })需要注意前端保存 token 要考虑安全风险高权限、长期有效的密钥不适合放在前端需要保护的密钥更适合放在服务端12. 使用环境变量管理 Token 和 Endpoint在项目中不建议把 token、API 地址直接写死在代码里。更常见的做法是使用环境变量。例如API_BASE_URLhttps://api.example.com API_TOKENYOUR_TOKEN API_MODELyour-model-name代码中读取后再组装请求const baseURL process.env.API_BASE_URL const token process.env.API_TOKEN fetch(${baseURL}/users, { method: POST, headers: { Authorization: Bearer ${token}, Content-Type: application/json }, body: JSON.stringify({ name: Tom, age: 18 }) })这样做的好处是本地、测试、生产环境可以使用不同配置token 不容易散落在业务代码中Endpoint 变更时更容易统一调整配合部署平台时更容易管理密钥但要注意不要把包含真实 token 的.env文件提交到公开仓库不要在日志中完整打印Authorization不要把高权限密钥放在前端构建产物里具体变量名以项目约定或接口文档为准13. API Endpoint、模型名和鉴权要分开看在配置 API 时很多人会把 Endpoint、模型名、Header 混在一起。实际排查时建议拆开13.1 EndpointEndpoint 是请求地址例如https://api.example.com/users它决定请求发到哪里。常见错误域名写错路径少了版本号多写或少写/把测试环境和生产环境混用13.2 AuthorizationAuthorization 决定你有没有权限Authorization: Bearer YOUR_TOKEN常见错误token 为空token 过期Bearer拼错Bearer后缺少空格复制了多余引号或换行符13.3 Content-TypeContent-Type 决定后端如何解析 BodyContent-Type: application/json常见错误JSON Body 配了表单类型表单 Body 配了 JSON 类型文件上传时手动乱写multipart/form-data; boundary...13.4 模型名或业务参数如果某些接口需要模型名、业务类型、用户 ID 等参数它们通常属于 Body 或 Query而不是 Header。例如{ model: your-model-name, messages: [] }这类字段是否需要、叫什么名字应以具体接口文档为准。14. 文件上传时 Content-Type 怎么处理文件上传通常使用Content-Type: multipart/form-data但在浏览器、Postman、Axios 这类工具里很多情况下不建议手动写完整的Content-Type。原因是文件上传需要boundary例如Content-Type: multipart/form-data; boundary----WebKitFormBoundaryxxx这个boundary通常由浏览器或请求库自动生成。如果你手动写死Content-Type: multipart/form-data反而可能导致后端无法正确解析文件。一般做法是Postman / ApifoxBody 选择form-data浏览器使用FormDataAxios传入FormData让请求库处理边界示例const formData new FormData() formData.append(file, file) axios.post(https://api.example.com/upload, formData, { headers: { Authorization: Bearer YOUR_TOKEN } })这里没有手动写Content-Type让 Axios 或浏览器自动处理。15. 常见报错排查401、403、415Header 配错后最常见的报错可以按下面顺序排查。报错常见原因排查方向401 Unauthorized没传 token、token 过期、Bearer 格式错误检查Authorization403 Forbiddentoken 有效但权限不够检查账号、角色、接口权限415 Unsupported Media TypeContent-Type不被支持改成接口文档要求的类型后端收不到参数Body 和Content-Type不匹配JSON 配 JSON表单配表单CORS 预检失败自定义 Header 或 Authorization 触发预检后端允许对应 Header、Method、Origin16. 401 Unauthorized 怎么排查遇到401 Unauthorized优先看鉴权。检查点Authorization: Bearer YOUR_TOKEN逐项确认是否真的传了AuthorizationBearer是否拼写正确Bearer后面是否有空格token 是否过期token 是否复制完整是否误带了引号、换行、尖括号当前接口是否要求的不是 Bearer而是X-API-Key可以先用 curl 验证curl https://api.example.com/users \ -H Authorization: Bearer YOUR_TOKEN如果 curl 也返回 401通常说明 token、权限或 Header 格式有问题。如果 curl 正常浏览器代码不正常则继续检查 CORS 或前端请求代码。17. 403 Forbidden 怎么排查403 Forbidden和401不一样。一般可以这样理解401你是谁服务端无法确认403知道你是谁但你没有权限常见原因当前账号没有接口权限token 权限范围不够使用了错误环境的 token签名权限不足接口限制了访问来源或角色排查方式确认 token 对应的账号确认账号是否有接口权限确认调用的是测试环境还是生产环境如果是签名认证检查签名范围和权限配置18. 415 Unsupported Media Type 怎么排查415 Unsupported Media Type通常和Content-Type有关。例如接口只支持 JSONContent-Type: application/json但你发送了Content-Type: text/plain就可能返回 415。排查步骤查看接口文档要求的Content-Type查看实际请求 Header查看 Body 是否和 Header 匹配使用 Postman 或 curl 复现如果是文件上传检查是否错误手写了boundaryJSON 请求推荐组合Content-Type: application/json{name:Tom,age:18}表单请求推荐组合Content-Type: application/x-www-form-urlencodednameTomage1819. Postman 能通浏览器代码不通怎么办这是很常见的问题。如果 Postman 能请求成功但浏览器里失败不一定是 Header 写错可能是浏览器跨域限制。尤其当前端请求带有Authorization: Bearer YOUR_TOKEN或者自定义 HeaderX-API-Key: xxx浏览器可能会先发送一个OPTIONS预检请求。后端需要正确返回允许信息例如Access-Control-Allow-Origin: https://your-frontend.example.com Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: Authorization, Content-Type如果后端没有允许Authorization或Content-Type浏览器会拦截请求。排查思路打开浏览器 DevTools查看 Network 面板看是否有OPTIONS请求失败看响应头中是否允许了对应 Header后端补充 CORS 配置注意CORS 是浏览器安全机制Postman 不受同样限制所以 Postman 能通不代表浏览器一定能通。20. 安全与最佳实践Header 配置不仅要能跑通也要注意安全。尤其是Authorization中的 token一旦泄露可能等同于登录态泄露。建议遵守这些规则不要把 token 放在 URL 中不推荐https://api.example.com/users?tokenxxx推荐Authorization: Bearer YOUR_TOKEN不要把真实 token 提交到 GitHub包括源码.envREADME示例截图接口调试记录不要在日志中完整打印 Authorization不推荐Authorization: Bearer eyJhbGciOi...可以打码Authorization: Bearer eyJhbGci...尽量使用 HTTPStoken 应该通过 HTTPS 传输避免明文暴露。前端不要保存高权限长期密钥前端代码最终会暴露给用户不适合保存高权限、长期有效的密钥。如果需要保护密钥更推荐前端 - 自己的后端 - 第三方 API由服务端保管密钥并转发请求。21. 新手配置 API Header 的推荐流程如果你正在接一个新接口可以按这个流程来第一步确认接口地址https://api.example.com/users确认域名路径API 版本HTTP 方法第二步确认鉴权方式查看文档要求的是哪一种Authorization: Bearer xxx或X-API-Key: xxx不要自己猜 Header 名。第三步确认 Body 格式如果 Body 是 JSON{name:Tom,age:18}就配置Content-Type: application/json如果是表单nameTomage18就配置Content-Type: application/x-www-form-urlencoded第四步用 Postman 或 curl 先验证curl 示例curl -X POST https://api.example.com/users \ -H Authorization: Bearer YOUR_TOKEN \ -H Content-Type: application/json \ -d {name:Tom,age:18}先保证最小请求能通。第五步再迁移到代码中fetch 示例fetch(https://api.example.com/users, { method: POST, headers: { Authorization: Bearer YOUR_TOKEN, Content-Type: application/json }, body: JSON.stringify({ name: Tom, age: 18 }) })Axios 示例axios.post( https://api.example.com/users, { name: Tom, age: 18 }, { headers: { Authorization: Bearer YOUR_TOKEN, Content-Type: application/json } } )22. FAQ22.1 Header 名大小写有影响吗HTTP Header 名通常不区分大小写。也就是说content-type: application/json和Content-Type: application/json语义上通常是一样的。但为了可读性和通用习惯建议写成Content-Type Authorization22.2 token 应该放 Header 还是 URL一般建议放 HeaderAuthorization: Bearer YOUR_TOKEN不建议放 URLhttps://api.example.com/users?tokenxxx因为 URL 更容易出现在浏览器历史记录服务器日志代理日志监控系统截图和分享链接泄露风险更高。22.3 可以同时写 Authorization 和 Content-Type 吗可以而且很常见。例如Authorization: Bearer YOUR_TOKEN Content-Type: application/json它们解决的是两个不同问题Authorization鉴权Content-Type说明请求 Body 格式两者不冲突。22.4 Content-Type 是 application/json 时Body 怎么写Body 应该是合法 JSON 字符串{name:Tom,age:18}在 JavaScript 中要这样写body: JSON.stringify({ name: Tom, age: 18 })不要直接写body: { name: Tom, age: 18 }22.5 Authorization 和 Cookie 有什么区别两者都可以表示登录态但机制不同。Authorization通常由客户端主动写入 HeaderAuthorization: Bearer xxxCookie更多用于浏览器会话浏览器会根据域名自动携带Cookie: sessionidxxx具体使用哪种方式取决于系统设计和接口文档。总结API Header 配置可以先记住三件事需要鉴权时先看文档要求的是Authorization、X-API-Key还是其他自定义 Header只要请求有 Body就让Content-Type和 Body 格式保持一致请求失败时按401、403、415分别排查 token、权限和 Body 类型对新手来说不需要一开始背所有 Header 字段。先把Authorization、Content-Type、Accept这几个最常见字段搞清楚再结合 Postman、curl、fetch、Axios 验证请求调试会顺很多。