浏览器原生JSON模块导入：用法、原理与兼容性实践

在前端工程化已经相当成熟的今天浏览器原生 JSON 模块导入反而是一件值得单独讲清楚的新特性。所谓 JSON 模块就是让浏览器像加载 JavaScript 模块一样加载一个.json文件并且通过 import attributes 语法告诉浏览器“这个模块应该按 JSON 格式解析”。它解决的痛点是过去要读取本地 JSON要么写一段fetch().then(r r.json())要么让 Webpack、Vite 在构建阶段把 JSON 内容打进 JS 产物而现在可以在不依赖构建工具、不写请求封装的情况下用import语句直接拿到 JSON 数据。整个过程对网络、缓存、模块依赖和错误处理都有明确语义也减少了“把 JSON 数据当作代码执行”的风险。本文以 Chrome/Edge 等 Chromium 系浏览器的稳定支持为基础从一个最小项目开始逐步讲解语法、环境、运行验证、兼容回退和生产注意事项。读完你可以判断自己的项目是否适合使用原生 JSON 模块也能在浏览器报错时快速定位是语法问题、MIME 问题还是兼容性问题。1. 先理解一句话JSON 模块导入是在解决哪一层问题1.1 浏览器加载 JSON 的传统方式到底哪里不顺在原生 JSON 模块出现之前前端拿到一份本地 JSON 数据通常有三条路每条路都有明显的代价。第一条路是fetch。这是最灵活的方式可以控制请求头、异常处理和缓存策略但代码重复度很高。每加载一份 JSON 都要写一次fetch(url).then(r r.json())还要处理 HTTP 状态码、网络异常、JSON 解析异常配置一多项目中就会出现大量相似工具函数。而且fetch没有模块语义数据不会被纳入模块依赖图想表达“这个页面必须依赖这份配置”只能靠代码顺序。第二条路是交给构建工具。Webpack、Vite 等工具默认会把 JSON 当作可导入的模块在构建阶段把 JSON 内容直接编译进 JS 产物。这种方式开发体验不错但有两个突出问题配置文件一变整个产物就得重新构建无法做到“只更新数据文件而不动代码”大型 JSON 会被塞进 bundle增大首屏解析成本。对低代码平台、可视化大屏、运行时可配置系统这类场景这往往是不能接受的。第三条路是把 JSON 直接写成 JS 对象。这种方式对小型演示项目可行但数据与代码耦合外部人员无法独立维护数据产品经理改一个字段也要进入代码仓库更谈不上按环境分发不同配置。JSON 模块导入把.json提升为浏览器的一等公民资源它有自己的模块格式有明确的 MIME 校验有默认导出可以静态导入也可以动态导入。应用配置、多语言包、表单 schema、Mock 数据这些原本需要“封装 请求 解析”的资源现在可以像导入一个 JS 模块一样简单、稳定。1.2 import attributes 的核心语法与工作原理JSON 模块依赖的是 TC39 的 import attributes 提案。简单说在import语句后面追加一段with { type: json }告诉浏览器这个模块说明符应该按 JSON 格式解析而不是按 JavaScript 解析。静态导入的写法import config from ./data/config.json with { type: json };动态导入的写法const module await import(./data/config.json, { with: { type: json } });重新导出的写法export { default } from ./data/config.json with { type: json };浏览器执行到这段语句时会先根据type: json确定模块解析方式然后请求资源、校验响应头中的Content-Type是否匹配application/json最后把 JSON 内容解析成一个普通 JavaScript 对象作为模块的default导出。这里有一个关键设计type不是可选的提示而是会影响模块解析方式的属性。早期提案叫 import assertions使用assert { type: json }后来改为 import attributes使用with { type: json }。改名就是为了强调它不只是“断言”而是真正决定模块加载行为的属性。1.3 支持范围浏览器、Node 与构建工具要分开看对 Web 开发者来说最关心的支持环境是浏览器。Chromium 系浏览器在较新稳定版本中已经默认支持 import attributes并开启 JSON 模块Firefox 和 Safari 的支持进度需要按目标版本确认不建议直接假设所有用户都在最新浏览器上。环境支持情况落地建议Chrome / EdgeChromium 内核较新稳定版本已支持 import attributes并默认启用 JSON 模块作为主要演示和自测环境Firefox已逐步跟进具体版本需要按发布时间线确认上线前在目标版本里跑一次验证Safari需要按目标版本确认在兼容矩阵中单独标记Node.js不同主版本支持程度不同部分版本需要实验开关或升级运行时服务端读 JSON 优先使用readFile或JSON.parseWebpack / Vite通常会把.json作为数据模块在编译期处理需要浏览器原生加载时单独配置不要默认它一定透传这里要特别提醒兼容性信息会随版本变化具体落地前要用官方发布说明或兼容性查询工具确认不要只凭一篇文章的版本号做决策。2. 环境准备三步让本地演示项目跑通2.1 三个前置条件HTTP 服务、正确 MIME、支持版本JSON 模块本质上是 ES Module因此它遵循模块脚本的所有约束。第一必须通过 HTTP 或 HTTPS 协议加载。浏览器规定模块脚本只在安全上下文或http://localhost下运行直接双击 HTML 文件通过file://打开会触发 CORS 错误。本地开发最简单的做法是起一个静态服务器。第二服务器返回.json文件时Content-Type必须是application/json。JSON 模块对 MIME 类型做严格校验如果服务器把文件当作text/plain返回模块加载会失败。这一点和普通fetch不同fetch默认不检查 MIME但模块加载会检查。第三浏览器版本要支持 import attributes。如果目标浏览器不支持静态导入会在语法解析阶段直接失败。注意不要只验证页面能打开还要在 DevTools 的 Network 面板确认请求确实发给了.json文件并且响应头Content-Type是正确的否则后面的排查会无从下手。2.2 最小项目结构创建一个名为json-module-demo的项目目录结构如下json-module-demo/ ├── index.html ├── app.js └── data/ ├── config.json └── locales/ ├── zh-CN.json └── en-US.jsonindex.html只需要引入一个模块脚本!DOCTYPE html html langzh-CN head meta charsetUTF-8 / titleJSON Module Demo/title /head body h1 idtitle加载中.../h1 ul idfeature-list/ul script typemodule src./app.js/script /body /htmldata/config.json放一份应用配置{ appName: JSON Module Demo, version: 1.0.0, features: [ { name: 原生导入, enabled: true }, { name: MIME 校验, enabled: true } ] }data/locales/zh-CN.json放一份语言包{ hello: 你好, world: 世界 }en-US.json内容类似只是值换成英语。这个结构虽然简单但已经覆盖了“静态配置”和“按需语言包”两种典型使用场景。2.3 启动服务器并检查响应头在项目根目录执行npx serve .或者使用 Python 自带服务器python -m http.server 8080两种方式都会把.json文件以application/json返回适合快速验证。启动后在浏览器打开http://localhost:8080然后用curl检查 JSON 响应头curl -I http://localhost:8080/data/config.json预期输出中应包含HTTP/1.1 200 OK Content-Type: application/json如果Content-Type是text/plain或text/html说明服务器 MIME 配置有问题需要先解决这一项再继续调试。MIME 正确之后进入核心用法。3. 完整用法静态导入、动态导入与语法迁移3.1 静态导入适合启动时就必须存在的配置对应用启动就要用到的配置使用静态导入最直接。在app.js中写入import config from ./data/config.json with { type: json }; const title document.getElementById(title); title.textContent config.appName; const list document.getElementById(feature-list); for (const feature of config.features) { const li document.createElement(li); li.textContent ${feature.name}: ${feature.enabled ? 开启 : 关闭}; list.appendChild(li); }静态导入的好处是确定性浏览器在加载app.js时就会解析出整个模块依赖图config.json会在脚本执行前加载并解析完成。如果 JSON 文件缺失、MIME 错误或内容解析失败错误会在模块加载阶段暴露而不是在运行到某一行时才炸出来。重新加载页面标题区域显示JSON Module Demo列表区域显示两条功能项。打开 DevToolsNetwork 面板中可以看到config.json请求并且它的类型会被识别为 module 资源。3.2 动态导入按需加载语言包或业务数据配置类数据适合静态导入语言包这类可能切换的资源适合动态导入。动态导入的第二个参数里同样通过with声明模块类型async function loadLocale(localeName) { const module await import(./data/locales/${localeName}.json, { with: { type: json } }); return module.default; } async function switchLocale(localeName) { try { const messages await loadLocale(localeName); console.log(hello 字段, messages.hello); } catch (error) { console.error(语言包加载失败, error); } } // 使用时 await switchLocale(zh-CN); await switchLocale(en-US);动态导入适合“不一定发生、发生后也不阻塞首屏”的加载场景。模板字符串可以动态拼接 URL所以根据用户语言加载对应语言包非常自然。注意动态导入返回的是模块命名空间对象JSON 模块的默认数据在module.default上不要直接使用module。3.3 assert 与 with 的关系为什么不能混用早期语法是assertimport data from ./data.json assert { type: json };当前标准写法是withimport data from ./data.json with { type: json };动态导入也一样// 旧写法 import(./data.json, { assert: { type: json } }); // 新写法 import(./data.json, { with: { type: json } });两套语法不能混用也不能互相替换。新代码统一使用with网上很多早期示例仍是assert抄代码时要注意区分。这里有一个容易混淆的细节静态导入的with属于 import 语法的一部分。浏览器如果完全不认识 import attributes会在解析阶段报语法错误导致整个模块脚本不执行而动态导入的import(url, options)在旧浏览器中语法上是合法的只是第二个参数会被忽略浏览器会尝试把 JSON 文件当作 JavaScript 模块加载最终报出SyntaxError或“没有 default 导出”之类的运行时错误。这个差异直接决定了兼容方案该怎么设计。注意静态 import 的with语法在不支持 import attributes 的浏览器中属于语法错误会导致整个模块脚本不执行。做兼容时不要上来就写静态 import要优先考虑动态导入加探测回退。4. 关键边界默认导出、绑定语义与 MIME 校验4.1 JSON 模块只有一个 default 导出没有具名导出这是 JSON 模块最容易踩的坑。下面这种写法会直接报错import { appName } from ./data/config.json with { type: json }; // 报错The requested module does not provide an export named appNameJSON 模块只提供default导出也就是整个 JSON 解析后的对象。想取字段先拿到default再解构import config from ./data/config.json with { type: json }; const { appName, version } config;如果是动态导入则需要写成const { default: config } await import(./data/config.json, { with: { type: json } });4.2 绑定是只读的对象内部仍然可改JSON 模块导入进来的绑定遵循 ES Module 的绑定语义绑定本身是只读的不能重新赋值但对象内部的属性可以修改。例如import config from ./data/config.json with { type: json }; config { a: 1 }; // TypeError: Assignment to constant variable. config.appName 运行期修改; // 可以执行对象属性发生了变更这里需要理解“绑定”和“对象内容”是两回事。config这个绑定不能换指向但它指向的对象仍然是普通 JS 对象属性可以被改。如果希望