azure static web apps 默认将请求回退到 index.html，导致 json 文件被当作 html 返回；本文详解通过修正 mime 类型配置或结合 azure functions 两种可靠方案，确保 json 资源以 application/json 类型正确响应。
azure static web apps 默认将请求回退到 index.html，导致 json 文件被当作 html 返回；本文详解通过修正 mime 类型配置或结合 azure functions 两种可靠方案，确保 json 资源以 application/json 类型正确响应。
在 Azure Static Web Apps 中部署 React 应用时，若直接将 .json 文件（如 data/config.json）放入 public/ 目录并尝试通过 fetch('/data/config.json') 加载，你可能会发现浏览器收到的是 index.html 的 HTML 内容，而非预期的 JSON 数据——控制台报错类似 Unexpected token '导航回退（navigationFallback）机制 和 MIME 类型配置不当 共同导致。
✅ 正确配置 staticwebapp.config.json
关键问题在于你当前的 MIME 类型设置：
"mimeTypes": {
".json": "text/json"
}
该写法存在两个问题：
- "text/json" 不是标准 MIME 类型（RFC 4627 明确推荐使用 application/json）；
- Azure Static Web Apps 在匹配静态文件时，若 MIME 类型未被正确识别，可能跳过类型声明，转而触发 navigationFallback，最终重写为 /index.html。
✅ 正确配置如下（注意：application/json 是唯一推荐值）：
{
"navigationFallback": {
"rewrite": "/index.html",
"exclude": [
"/static/media/*.{png,jpg,jpeg,gif,bmp}",
"/static/css/*",
"/data/*.json", // ? 显式排除 JSON 路径，防止被重写
"*.json"
]
},
"mimeTypes": {
".json": "application/json" // ✅ 标准且强制生效
}
}
? 重要提示：exclude 数组支持通配符，但需注意顺序与精确性。建议将 *.json 或具体 JSON 路径（如 /data/*.json）加入 exclude，确保请求不被 rewrite 规则捕获。否则即使 MIME 类型正确，文件仍可能被重定向至 index.html。
? 替代方案：使用 Azure Functions 提供 API 端点（推荐用于动态/敏感数据）
若 JSON 内容需服务端处理（如读取环境变量、调用其他 API、鉴权），或你希望彻底规避静态路由限制，Azure Functions 是更健壮的选择。
- 在项目根目录下创建 api/hello/index.js（函数路径会映射为 /api/hello）：
module.exports = async function (context, req) {
context.res = {
status: 200,
headers: {
'Content-Type': 'application/json',
'Access-Control-Allow-Origin': '*' // 开发阶段可加，生产建议按需限制
},
body: {
message: 'Hello from Azure Function!',
timestamp: new Date().toISOString()
}
};
};
- 在 React 组件中调用：
useEffect(() => {
fetch('/api/hello')
.then(res => {
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
})
.then(data => console.log(data))
.catch(err => console.error('Failed to load JSON:', err));
}, []);
✅ 优势：
- 完全绕过静态回退逻辑，无 MIME 配置风险；
- 支持身份验证、日志、扩展性部署；
- 可轻松集成 Key Vault、Cosmos DB 等后端服务。
⚠️ 注意事项与调试技巧
- 缓存陷阱：浏览器或 CDN 可能缓存了旧的 index.html 响应。测试前请强制刷新（Ctrl+Shift+R）或禁用缓存（DevTools → Network → ☑️ Disable cache）。
- 路径验证：确保 JSON 文件实际存在于构建输出目录（如 dist/data/config.json），且 staticwebapp.config.json 位于项目根目录（与 hosting.json 同级）。
- 检查响应头：在浏览器 DevTools → Network → 点击请求 → Headers → 查看 Content-Type 是否为 application/json，同时确认 Response 标签页内容是否为原始 JSON。
- 本地验证：使用 npx serve -s build 无法复现此问题（它无 navigationFallback），务必在真实 Azure 静态站点上测试。
✅ 总结
| 方案 | 适用场景 | 关键操作 |
|---|---|---|
| 修正 staticwebapp.config.json | 静态 JSON 文件（如配置、文案、mock 数据） | 设置 "application/json" + exclude: ["*.json"] |
| Azure Functions | 动态 JSON、需服务端逻辑、安全敏感数据 | 创建 /api/* 函数，显式设置 Content-Type 头 |
二者并不互斥：你可以混合使用——静态资源走配置优化，业务 API 走 Functions。只要明确区分“静态资产”与“API 接口”，就能在 Azure Static Web Apps 中稳定交付正确的 JSON 响应。
