如何解决Unexpected token ‘<’, "<!doctype "… is not valid JSON 报错问题
摘要
在前端开发或Node.js应用中，当使用fetch、XMLHttpRequest或类似API请求数据并尝试解析为JSON时，经常遇到Unexpected token '<', "<!doctype "... is not valid JSON错误。这通常发生在请求的响应不是有效的JSON格式，而是HTML文档（如服务器返回的错误页面、登录页面或404页面），导致JSON.parse()或.json()方法失败。异常出现的开发场景包括构建RESTful API客户端、实时数据获取应用或微服务交互，例如在React/Vue项目中从后端API拉取用户数据，但由于URL错误、网络重定向或服务器配置问题，响应体以<!doctype html>开头的技术细节引发解析异常。这种错误的技术细节涉及HTTP响应头（如Content-Type未设为application/json）、浏览器安全机制（如CORS）和JavaScript的严格JSON解析规则，若未处理，会中断应用流程，影响用户体验。
文章目录
开发环境介绍
本篇文章基于以下开发环境进行问题排查和解决方案验证：
- JavaScript运行时：Node.js 20.x 或浏览器环境（如Chrome 120+）。
- 操作系统：macOS（例如macOS Sonoma或更高版本，注意网络代理配置）。
- IDE：VS Code 1.92 或 PyCharm 2025（若用于全栈开发，支持JavaScript插件）。
这些环境是典型的Web开发配置，尤其在前后端分离项目中常见。如果你的环境不同（如Windows上的Edge浏览器），解决方案原理相似，但调试工具可能需调整。
问题分析：为什么会出现Unexpected token错误
Unexpected token '<', "<!doctype "... is not valid JSON错误表明JavaScript解析器在处理响应时遇到了非JSON起始字符，通常是HTML的DOCTYPE声明。这往往源于服务器未返回预期JSON，而是HTML错误页面。常见触发场景包括：
- API端点不存在，导致服务器返回404 HTML页面。
- 未授权请求被重定向到登录HTML页面。
- 响应头Content-Type错误设置为text/html。
注意：这个错误并非JSON语法问题，而是响应内容类型不匹配。如果直接
JSON.parse('<html>...')，必然失败。
为了可视化问题排查流程，我们可以使用Mermaid流程图来描述典型诊断步骤：
graph LR
A[发起fetch请求] -- 接收响应 --> B{检查response.ok}
B -- 否 --> C[查看status code，如404/500]
C -- 处理 --> D[修正URL或服务器端点]
B -- 是 --> E{Content-Type是application/json}
E -- 否 --> F[服务器配置错误，设置正确头]
E -- 是 --> G[尝试response.json()]
G -- 失败 --> H[打印response.text()调试内容]
H -- 显示HTML --> I[检查CORS或重定向]
G -- 成功 --> J[问题解决，继续开发]
这个流程图展示了从请求发起到逐步排查的逻辑路径，帮助开发者系统地定位问题。
解决方案一：检查请求URL和服务器端点
最常见原因是URL拼写错误或API端点不存在，导致服务器返回HTML错误页面。
步骤详解
- 验证URL：在浏览器中直接访问URL，查看是否返回JSON。若返回HTML，修正URL（如
/api/users而非/users）。 - 使用Postman或curl测试：运行
curl -i https://yourapi.com/endpoint，检查响应头和体。 - 扩展：如果URL动态生成，添加日志打印请求URL前确认。
提示：总是使用绝对URL避免相对路径问题。
解决方案二：处理网络和重定向问题
网络问题或服务器重定向（如301/302到HTML页面）可能导致错误，尤其在跨域请求中。
步骤详解
- 检查重定向：在DevTools的Network面板查看响应链，若有重定向到登录页，添加认证头（如Authorization: Bearer token）。
- 网络代理/VPN：临时禁用代理测试，如果是公司网络，配置代理例外。
- 扩展：使用
fetch的redirect: 'manual'选项手动处理重定向。
解决方案三：验证响应类型并添加错误处理
在解析前未检查响应类型是常见疏忽。
步骤详解
- 修改代码：在
fetch后添加if (!response.ok) throw new Error('Bad response');。 - 检查Content-Type：
if (response.headers.get('Content-Type') !== 'application/json') { console.log(await response.text()); }。 - 使用try-catch包裹
await response.json()，捕获错误并打印response.text()调试。 - 扩展：如果响应是HTML，解析DOM提取错误信息（如使用DOMParser）。
解决方案四：CORS和请求头配置
CORS问题可能导致预检请求失败，服务器返回HTML。
步骤详解
- 服务器端添加CORS头：如Express中用
cors中间件。 - 请求头设置：添加
headers: { 'Accept': 'application/json' }确保期望JSON。 - 扩展：浏览器模式下，使用
mode: 'cors'在fetch选项中。
解决方案五：服务器端问题和版本兼容
服务器配置错误或库版本不兼容。
步骤详解
- 检查服务器日志：确认端点是否返回JSON而非错误HTML。
- 更新库：如Node.js的express，确保
res.json(data)而非res.send('<html>')。 - 扩展：如果使用旧版浏览器，polyfill fetch或使用axios库，它有内置错误处理。
解决方案六：其他扩展可能性
除了上述，以下是更多潜在原因及解决：
- 缓存问题：添加
cache: 'no-store'到fetch选项，或清空浏览器缓存。 - 代理服务器干扰：如Nginx配置错误返回HTML，检查proxy_pass。
- JSON字符串手动解析：如果数据从其他来源，确保无HTML注入。
- 开发 vs 生产环境：环境变量差异导致URL错，用dotenv管理。
总结表格：常见原因及快速修复
以下表格总结了所有解决方案，便于快速参考：
| 原因分类 | 具体问题 | 快速修复命令/步骤 | 适用场景 |
|---|---|---|---|
| URL相关 | 端点不存在 | 验证URL并修正 | 初次请求 |
| 网络问题 | 重定向到HTML | 处理redirect或添加认证 | 授权API |
| 响应检查 | 未验证类型 | 添加response.ok和Content-Type检查 | 所有fetch |
| CORS配置 | 跨域失败 | 服务器添加CORS头 | 前后端分离 |
| 服务器端 | 返回HTML错误 | 检查res.json()使用 | Node.js后端 |
| 扩展 | 缓存干扰 | cache: ‘no-store’ | 重复请求 |
| 头设置 | 未指定Accept | headers: {‘Accept’: ‘application/json’} | 浏览器请求 |
这个表格覆盖了80%以上的场景，帮助你高效排查。
亲爱的读者，如果你正为这个JSON解析Bug纠结，这些实用方法能让你迅速摆脱困境，重回高效 coding。更多Bug解决方案请查看==>全栈Bug解决方案专栏https://blog.csdn.net/lyzybbs/category_12988910.html，那里汇集了无数开发者的智慧，愿它成为你编程路上的可靠伙伴！