浏览器原生支持JSON模块导入：语法、原理与实战指南

做前端开发这些年JSON 大概是每天都会打交道的格式接口返回的数据是 JSON项目配置文件是 JSON国际化语言包也是 JSON。但在浏览器里直接import一份 .json 文件过去几乎是“想都不敢想”的操作——要么老老实实写fetch再手动JSON.parse要么依赖 Vite、Webpack 这类构建工具在打包阶段把它转换成 JS 模块。最近这个局面终于开始松动现代浏览器已经原生支持 JSON 模块导入静态 JSON 文件可以像普通的 ES Module 一样被import进来。这篇文章就从背景、语法、完整示例到常见报错排查把这个新特性一次讲清楚。1. 背景为什么浏览器原生 JSON 模块导入值得关注1.1 传统 JSON 加载方式的痛点先回顾一下过去在浏览器里加载 JSON 的常规做法。最通用的是fetch方案先发出网络请求等服务端返回后调用response.json()解析。这段逻辑本身不复杂但在“页面初始化时就要用到的静态配置”这种场景里每次都手动写一套异步函数确实有些重复。而且fetch拿到的数据没有“模块级”的缓存语义不像 ES Module 那样只解析一次、在多个文件间共享同一个实例。另一个主流做法是构建工具方案。Vite、Webpack、Rollup 都支持直接import data from ./data.json开发体验很舒服写法也简洁。但这个能力是绑定在构建工具上的一旦项目切换成“无打包、纯浏览器运行”的模式这条路就走不通。也就是说浏览器平台本身一直缺少一个“把 JSON 当模块导入”的标准能力。1.2 什么是 JSON 模块JSON 模块JSON Module是浏览器对 ES Module 体系的一种扩展在import语句后面附加一段 import attributes导入属性声明这个模块的资源类型是json浏览器就会按照 JSON 的规则去解析文件并把解析结果作为该模块的默认导出default export。它解决的核心问题很直接让 JSON 文件成为浏览器模块体系里的“一等公民”既可以被静态import处理也可以被动态import()加载还能参与模块缓存。换句话说这份能力本来就应该属于浏览器平台构建工具只是提前帮我们实现了而已。1.3 典型应用场景哪些场景最适合使用原生 JSON 模块第一个是前端静态配置文件。比如站点元信息、导航菜单结构、功能开关这类几乎不变的数据直接import成模块整个应用共享一份解析结果比在组件里反复fetch干净得多。第二个是国际化语言包。大型应用的 i18n 通常会拆成zh-CN.json、en-US.json等多个文件配合动态导入按需加载用户切到某个语言时再加载对应模块天然享受代码分割。第三个是纯静态的图表配置、地图 GeoJSON 数据、表格默认筛选项等。这类数据不依赖运行时接口适合作为静态资源随应用一起发布。第四个是测试夹具test fixture。在纯前端的 DEMO、本地调试页或自动化测试环境里把测试数据用 JSON 模块导入省去构造网络请求的麻烦。2. 环境准备与浏览器支持情况2.1 浏览器支持情况先说结论Chrome 123 以及同内核的 Edge 123 开始JSON 模块已经默认开启。Firefox 早期需要通过about:config打开实验开关Safari 也在后续版本逐步跟进。由于版本迭代速度比较快上线到生产环境之前务必结合你面向的用户群体确认目标浏览器的兼容范围。如果项目需要兼容较旧的浏览器原生 JSON 模块暂时还不能作为唯一方案。比较稳妥的做法是先用原生 JSON 模块开发同时保留一个基于fetch的降级加载函数用特性检测决定走哪条分支。2.2 必须通过 HTTP 服务访问JSON 模块和普通 ES Module 一样有一个硬性运行条件必须通过http://或https://协议访问页面。直接用file://协议双击打开 HTML 是不行的浏览器会因模块跨域策略拒绝加载。这一点和传统script标签很不一样很多新手踩的第一个坑就在这里。本地开发时随便起一个静态文件服务器即可后面实战部分会给出具体命令。2.3 MIME 类型要求服务端返回 .json 文件时HTTP 响应头的Content-Type必须是 JSON 类型。标准做法是application/jsontext/json以及以json结尾的类型例如application/ldjson也被规范允许。大多数静态服务器默认配置是对的但如果你的服务器自定义过映射关系把.json当成了text/plain输出浏览器在加载模块时就会直接拒绝并抛出一个与 MIME 类型相关的报错。排查方法很简单在终端里用 curl 看一下响应头curl -I http://localhost:8080/data.json正常返回类似这样HTTP/1.0 200 OK Content-Type: application/json如果Content-Type不是 JSON 类型优先检查静态服务器配置。2.4 特性检测思路JSON 模块的语法在旧浏览器里属于未知语法静态import一旦解析失败整个模块脚本都会挂掉。所以需要降级的时候建议用动态导入做一次探测把“是否支持”变成可判断的布尔值// 思路示例用动态导入探测当前浏览器是否支持 JSON 模块 async function checkJsonModuleSupport() { try { await import(./data.json, { with: { type: json } }); return true; } catch (error) { // 不支持、文件不存在或 MIME 不正确都会走到这里 return false; } } const support await checkJsonModuleSupport(); console.log(当前浏览器是否支持 JSON 模块, support);这段代码里无论 JSON 文件是否存在只要浏览器不支持 import attributes动态导入基本都会失败从而返回false。如果探测的目标文件路径不存在把它换成一个小体积的真实 JSON 文件即可。3. 核心语法与原理解读3.1 静态导入语法静态导入是 JSON 模块最直接的用法在普通import语句后面加上with { type: json }import siteConfig from ./data.json with { type: json }; console.log(siteConfig.name);这段代码的含义是告诉浏览器“请把./data.json当作 JSON 模块来加载”。解析完成后JSON 文件的根内容会成为模块的默认导出。如果 JSON 根内容是对象siteConfig就是那个对象如果是数组就是那个数组也可以是字符串、数字等基本类型。需要注意的是JSON 模块没有命名导出named exports所以不能用import { name } from ./data.json这种方式。必须通过默认导出拿到整个 JSON 内容再在代码里解构或取属性。3.2 动态导入语法按需加载时使用动态导入把 import attributes 作为import()的第二个参数传入// 在 async 函数中使用 const { default: data } await import(./data.json, { with: { type: json } }); console.log(data);动态导入返回的是一个模块命名空间对象module namespace objectJSON 的解析结果在这个对象的default属性上。这里最容易犯的错误是忘记取.default直接打印模块对象结果发现拿到的不是 JSON 数据。JSON 模块也支持转发导出这在封装公共数据模块时很实用// 例如在 config/index.js 中统一导出 export { default } from ./data.json with { type: json };3.3 with 与 assert 的历史变化如果你翻看 2023 年之前的资料会看到一种用assert关键字的旧语法// 旧的 import assertions 写法已废弃 import data from ./data.json assert { type: json };这是提案早期的写法后来标准组织把关键字从assert换成了with提案名称也从 Import Assertions 改成了 Import Attributes。原因在于assert的语义是“断言、校验”暗示浏览器应该去验证这个类型是否正确但 JSON 文件本身并没有可验证的机制这里更像是“附带属性告诉加载器按什么类型处理”。换成with之后语义更贴近实际行为。在实际开发中遇到assert语法要主动改为with。虽然部分浏览器暂时兼容旧写法但控制台会给出弃用警告后续版本大概率会移除。3.4 为什么必须显式声明类型有的同学可能会问为什么这里不能省略with { type: json }让浏览器自动识别呢这背后是一个安全设计考虑。JSON 语法和 JavaScript 表达式存在重叠一个本质上是 JSON 的文件某些内容也完全可能被当成合法脚本去执行。如果没有显式声明类型攻击者一旦能把一份恶意 JSON 放到静态资源目录或 CDN 上再诱导页面以脚本方式加载它就存在被当成 JavaScript 执行的风险。import attributes 相当于在“资源类型”和“模块加载器”之间建立了一道硬边界声明了type: json浏览器就只按 JSON 解析永远不把它当脚本执行。早期 JSONP 和动态脚本加载带来的安全性问题在这个机制下被从根上堵住了。这也是为什么标准不倾向于让浏览器“自动猜测”模块类型。3.5 JSON 的严格语法约束JSON 模块最终是由浏览器内置的 JSON 解析流程处理的所以必须遵守 JSON 格式的严格语法不能写注释不能有尾逗号字符串必须使用双引号属性名也必须加双引号。很多从 JavaScript 配置文件转过来的开发者习惯性往 .json 文件里塞注释或尾逗号结果模块加载直接失败。如果你的配置文件确实需要注释要么改成.jsonc或.js格式要么继续使用构建工具方案原生 JSON 模块并不负责“宽容地”解析这些内容。4. 完整实战演示下面通过一个完整的小项目演示静态导入和动态导入两种用法。4.1 项目结构设计先规划目录结构项目很小但足够看清楚 JSON 模块的使用方式json-module-demo/ ├── data.json # 静态导入的 JSON 数据 ├── extra.json # 动态导入的 JSON 数据 ├── index.html # 页面入口 └── main.js # 页面主模块4.2 编写 JSON 数据文件先准备data.json内容模拟一个站点基础配置{ site: { name: 前端实验室, domain: fe.lab.example.com, version: 2.1.0 }, nav: [ { text: 首页, url: / }, { text: 文档, url: /docs }, { text: 关于, url: /about } ], features: [json, modules, import-attributes, esm] }再准备extra.json用来演示动态导入{ announcement: 本站于每周六维护请合理安排发布时间。, copyright: 2024 前端实验室 }注意这两个文件都没有注释和尾逗号这是 JSON 模块加载成功的必要条件。4.3 编写入口 HTML 文件index.html里引入主模块同时预留一个按钮用于触发动态导入!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title浏览器原生 JSON 模块导入示例/title style body { font-family: system-ui, sans-serif; max-width: 720px; margin: 40px auto; padding: 0 16px; line-height: 1.7; } .nav li { display: inline-block; margin-right: 16px; } code { background: #f4f4f4; padding: 2px 6px; border-radius: 4px; } /style /head body h1 idtitleJSON Module Demo/h1 p idmeta/p ul idnav classnav/ul p idtip/p button idloadExtra加载额外配置/button p idextraInfo/p script typemodule src./main.js/script /body /html页面会显示站点信息、导航菜单和一个按钮点击按钮后动态加载extra.json。4.4 编写主模块 main.jsmain.js首先用静态导入加载data.json然后把数据渲染到页面import siteConfig from ./data.json with { type: json }; document.getElementById(title).textContent siteConfig.site.name; document.getElementById(meta).textContent ${siteConfig.site.domain} · 版本 ${siteConfig.site.version}; const navList document.getElementById(nav); for (const item of siteConfig.nav) { const li document.createElement(li); const link document.createElement(a); link.href item.url; link.textContent item.text; li.appendChild(link); navList.appendChild(li); } document.getElementById(tip).textContent 当前特性${siteConfig.features.join( / )}; console.log(JSON 模块静态导入成功, siteConfig);接着给按钮绑定事件使用动态导入加载extra.jsonconst loadExtraButton document.getElementById(loadExtra); const extraInfo document.getElementById(extraInfo); loadExtraButton.addEventListener(click, async () { try { const { default: extra } await import(./extra.json, { with: { type: json } }); extraInfo.innerHTML strong公告/strong${extra.announcement}br small${extra.copyright}/small; } catch (error) { console.error(动态导入 JSON 模块失败, error); extraInfo.textContent 加载失败请查看控制台错误信息。; } });这段代码覆盖了两个关键点一是动态导入需要解构出default属性二是动态导入可能失败必须用try/catch兜底避免未捕获的异常影响页面其他功能。4.5 启动本地服务并验证在json-module-demo目录下启动一个静态文件服务器。Python 环境可以直接用python3 -m http.server 8080如果没有 Python也可以用 Node.js 生态的servenpx serve -l 8080 .然后在浏览器访问http://localhost:8080打开开发者工具的控制台应该能看到类似输出JSON 模块静态导入成功 {site: {…}, nav: Array(3), features: Array(4)}页面区域会显示“前端实验室”、域名和版本号导航菜单渲染出“首页 / 文档 / 关于”。点击“加载额外配置”按钮下方会显示公告和版权信息控制台没有报错说明动态导入也成功了。这里有一点值得留意打开开发者工具的 Network 面板找到data.json和extra.json两条请求它们的响应头Content-Type都应该是application/json。如果某一步报“MIME type”错误问题基本就出在这里。5. 与 fetch / 构建工具方案的对比5.1 fetch 方案回顾传统的fetch方案写法如下async function loadJsonByFetch() { const response await fetch(./data.json); if (!response.ok) { throw new Error(HTTP 请求失败${response.status}); } return response.json(); }它的优势是灵活可以自定义请求头、控制缓存策略、处理不同的 HTTP 状态码适合加载运行时接口数据。缺点也很明显无法在模块顶层静态import多个文件共用同一份数据时需要额外写缓存逻辑而且每次都走异步回调流程代码相比直接import要多几行。5.2 构建工具方案对比Vite、Webpack 这类工具早已支持import data from ./data.json背后的原理是在构建阶段把 JSON 内容转成 JS 对象再生成一段导出默认值的模块代码。对工程化项目来说这是一种很成熟的方案一直会继续使用。两者的关系不是“谁替代谁”而是分层不同构建工具方案解决的是“工程内模块化”浏览器原生 JSON 模块解决的是“平台级模块化”。无构建场景、纯静态页面、小工具脚本里原生 JSON 模块的价值体现得最明显。5.3 三种方案对比方案运行环境是否需要构建工具支持静态顶层导入典型适用场景fetch JSON.parse浏览器否否接口数据、动态请求、需要精细控制请求参数的场景构建工具 JSON 导入构建后的浏览器产物是是绝大多数现代前端工程浏览器原生 JSON 模块现代浏览器否是纯静态配置、无打包场景、按需加载的小型数据6. 常见问题与排查思路问题现象常见原因解决思路模块加载报 MIME type 错误服务端没有返回 JSON 类型响应头检查静态服务器配置用 curl 查看 Content-Type直接双击 HTML 打不开页面file:// 协议下模块被浏览器拦截改用 python3 -m http.server 或 npx serve 启动本地服务动态导入拿到的不是 JSON 数据忘了取模块命名空间对象的 default 属性使用const { default: data } await import(...)控制台出现