浏览器原生JSON模块导入：语法、兼容性与工程化实践

浏览器原生 JSON 模块导入，最近在社区里引起了不少讨论。简单说，以后前端可以直接用import config from './config.json' with { type: 'json' }这种方式，让浏览器自己去加载和解析 JSON，不用再经过 fetch 回调、不用把 JSON 转成 JS 文件，也未必需要打包器层面单独做处理。

这个特性适合前端开发者、工程化搭建同学，以及经常维护静态配置、i18n 文案、mock 数据的人去关注。真正值得在意的点不是“浏览器又加了个新功能”，而是“它到底能在什么场景里稳定落地”。下面这篇内容，我会围绕语法变化、兼容性、最小示例、批量加载、工程化降级和排查链路来拆解，尽量按实际跑起来的状态来写。

1. 这个特性解决什么问题，先别急着欢呼，看清使用边界

1.1 没有原生 JSON 模块之前，大家是怎么写的

以前在一个纯浏览器项目里读取 JSON，比较常见的有三条路。

第一条路是fetch。写一个网络请求，等异步返回，再手动JSON.parse()。如果只是读一份配置，问题不大；但当项目里很多文件都在读 JSON，你会发现自己要处理各种 loading 状态、错误状态、缓存状态，代码很容易散落各处。

第二条路是把 JSON 复制进一个 JS 文件，再用export default导出。比如建一个config.js，里面写export default { ... }。这种方式的优点是同步加载，代码写起来简单，代码打包时也能直接被模块图看到。缺点是文件本身不再是纯 JSON，很多工具链路没法直接复用，维护时要多一层格式转换。

第三条路是用打包器处理。Webpack、Vite、Rollup 很早就能支持import data from './data.json'，背后会把 JSON 自动解析成模块。这个体验已经很接近现在说的“原生 JSON 模块导入”，但它依然属于“构建期能力”。只要项目离开了打包器，直接在浏览器环境里裸跑，这条路径就不成立。

所以浏览器原生 JSON 模块导入真正解决的核心问题就是：让浏览器在运行时模块系统里直接识别并加载 JSON 文件，不需要中间再套一层 JS 转换，也不需要依赖打包器替你翻译。

1.2 原生 JSON 模块导入能做什么，不能做什么

先说能做什么。

• 支持静态导入：import data from './data.json' with { type: 'json' }
• 支持动态导入：const data = await import('./data.json', { with: { type: 'json' } })
• 支持进入浏览器的模块依赖图，可以被模块缓存、预加载等机制统一接管。
• 和普通 import 一样，同一个 JSON 模块在同一页面里只会被真正请求一次，后续复用模块实例。

再看不能做什么。

• 只能拿到默认导出。也就是说，import data from './data.json'可以直接用，但import { title } from './data.json'这种具名导入没有办法直接工作。
• 加载的是纯 JSON 内容，不是 JSONC，也不是 JSON5。文件里不能带注释，不能带没有双引号的 key，否则会走 JSON.parse 解析并直接报错。
• 加载过程中你不能插入中间层去处理请求头、超时重试或自定义缓存策略，这些逻辑只能包在动态导入外层去写。
• JSON 模块一旦加载完成，返回的是当时解析出来的 JS 对象快照。你在内存里改了这个对象，不会写回文件，也不会影响其他模块再次引用。

简单理解，这是一个“把 JSON 当作模块资产”的机制，不是“把 JSON 当实时接口”的机制。适合的是静态内容、低频变化的内容、需要随模块加载的内容，不适合高频轮询、服务端动态数据和请求参数经常变化的场景。

2. 语法与核心原理，把 import attributes 一次性讲清楚

2.1 新语法与旧语法，知道为什么会有with

现在代码里最常见的是这种写法：

import data from './data.json' with { type: 'json' };

这行代码里，with { type: 'json' }被称为 import attributes，中文可以叫导入属性。它告诉浏览器：请把这个模块按 JSON 类型来解析，先做一次 JSON.parse，然后把解析结果作为默认导出暴露给当前模块。

如果你在早期文章或者老代码里看到下面这种写法，也不要奇怪：

import data from './data.json' assert { type: 'json' };

这是更早版本使用过的关键字，当时叫 import assertions，中文翻译是导入断言。后来规范调整，命名从assert改成了with，语义也从“断言这个模块是什么类型”改成了“用这些属性来匹配加载方式”。

这个变化解释了一个很多人踩过的坑：你在网上搜到 JSON 模块导入的代码，版本不同，写法可能不一样。写代码前先确认要跑的运行时支持哪种语法。如果浏览器比较新，优先用with，因为它更接近当前阶段的规范方向。

2.2 模块加载流程与默认导出

先看一个最小场景。假设目录下有两个文件：

// data.json { "title": "hello json module", "list": [1, 2, 3] }

// main.js import data from './data.json' with { type: 'json' }; console.log(data.title); console.log(data.list.length);

当浏览器解析到main.js时，会先把main.js当作一个模块加载。执行到import data这一行，浏览器会继续请求./data.json，然后用type: 'json'告诉模块加载器，这个响应需要按 JSON 处理。响应拿到后，浏览器内部执行一次JSON.parse，解析成功的对象会成为这个模块的默认导出。

这里需要注意两件事。

第一，JSON 模块没有具名导出。所以你只能写成import data from，不能写import { title } from。如果你确实需要解构，可以先拿到默认导出对象，再手动解构：

import data from './data.json' with { type: 'json' }; const { title, list } = data;

第二，默认导出的是解析后的对象，不是字符串，也不是一个提供.json()方法的 Response。这一点和 fetch 完全不同。fetch 拿到响应后还要一层解析，JSON 模块导入直接把解析步骤内置了。

2.3 与 fetch 和打包器导入的深层差异

原生 JSON 模块导入和 fetch 的本质区别，不只是“少写几行代码”，而是模块语义不同。

fetch 是运行时网络请求，它不在模块依赖图里。你用 fetch 加载 JSON，代码能不能执行、什么时候执行、加载失败怎么处理，全部由业务代码自己负责。而 JSON 模块导入是模块加载器的一部分，它可以被静态分析、缓存、预加载、tree-shaking 工具观察。

用打包器导入 JSON 是另一种情况。Vite、Webpack 里的import data from './data.json'本质上是在构建阶段把 JSON 内容转成 JS 模块输出，很多打包器遇到这种导入会自动启用 JSON 解析插件。问题是，这种导入语法在原生浏览器环境里并不一定被支持，或者说至少不会被当作原生 JSON 模块处理。换句话说，一个运行在 Vite 里的项目可以直接写import data from './data.json'，但这不代表浏览器已经原生支持相同语法；这是两套体系。

真正需要区分这两种场景：项目里有没有构建器，决定了你要不要写with { type: 'json' }。

3. 环境准备与兼容性，先卡条件再写代码

3.1 浏览器端的最小运行条件

要在原生浏览器环境里验证 JSON 模块，需要准备下面几个条件。

第一，浏览器版本要足够新。这个特性经历过语法调整，早期版本可能只支持assert，新版才支持with。不要凭一个旧教程里的结论就认为所有现代浏览器都能跑。最稳妥的办法是写一个最小示例，在目标浏览器里直接测一遍。

第二，不能直接用file://协议打开页面。模块加载天然受 CORS 限制，如果你双击 HTML 文件，浏览器会把页面当成一个本地文件，JSON 模块请求也会被同源策略拦下来。这几乎是新人遇到最多的一个问题。本地调试至少需要一个静态服务器，比如通过npx serve或者python3 -m http.server。

第三，JSON 文件的 MIME 类型必须是application/json。如果服务器返回了text/plain之类的类型，模块加载器可能拒绝把响应当作 JSON 模块处理，控制台会直接报错。大部分静态服务器对.json后缀都能返回正确类型，但如果你用了自定义后端，比如某些动态路由、接口网关，就需要额外检查响应头。

第四，确认页面顶层模块加载入口正确。浏览器原生 JSON 模块必须通过模块脚本进入，也就是说 HTML 里要么写<script type="module" src="./main.js"></script>，要么在另一个模块脚本里间接 import 它。普通<script>标签里不能直接写import语法。

3.2 Node.js 环境下的 JSON 模块

如果你不只写浏览器前端，还会用 Node.js 做脚本、接口或 SSR，同样有机会接触 JSON 模块。

在 Node.js 的 ESM 环境里，加载 JSON 模块也需要显式声明类型。比如：

import data from './data.json' with { type: 'json' }; console.log(data);

使用之前要确认几件事：

• 项目里已经启用 ESM，也就是package.json里设置了"type": "module"，或者文件后缀用.mjs。
• Node.js 版本要支持 import attributes。不同版本对这个特性的支持进度不一样，安装长期稳定版之前，先看一眼官方文档里的支持表。
• 如果 Node.js 版本识别不了with，但能识别更早的assert，可以临时用旧写法；不过更推荐直接升级到支持新语法的版本，避免后续代码长期停在旧技术分支上。

Node.js 里加载 JSON 模块还有一个实际价值：没有网络层的 CORS 问题，文件读取和处理都由运行时完成，调试起来比浏览器环境更直接。你可以先在 Node 里验证 JSON 文件内容和代码逻辑，再放到浏览器里看页面表现。

3.3 打包器和 TypeScript 需要单独确认

如果你在项目里使用 Vite、Webpack、Rollup 或 TypeScript，不要假设浏览器原生支持就代表这些工具全都支持。

很多打包器对 JSON 的处理方式仍然走的是构建插件，而不是透传浏览器的 import attributes。举个例子，你在 Vite 项目里写import data from './data.json' with { type: 'json' }，构建时 Vite 可能把它解析成普通 JSON 导入，并把with语法保留在产物里，也可能直接报语法错误，具体取决于 Vite 版本和 esbuild 版本。因此，跨工具链使用这个特性，必须先跑一次构建，再看产物代码和目标浏览器表现。

TypeScript 里有一个容易踩的点。旧版本 TypeScript 可以通过resolveJsonModule支持普通 JSON 导入，但如果你在 import 后面带上with或assert，TypeScript 解析器需要能识别 import attributes 语法。你可以这样处理：先确认 TypeScript 版本是否支持该语法，同时在tsconfig.json里开启resolveJsonModule。如果编译阶段一直报错，优先检查 TS 版本，而不是怀疑浏览器不支持。

最后再强调一次：原生能力、打包器能力、语言编译能力，是三条不同的线，不要只测浏览器端能跑就默认项目里所有环节都能跑。

4. 从最小示例跑通，覆盖启动、验证、结果判断全路径

4.1 准备目录与三个文件

为了把整个链路看清楚，建议亲手建一个最小目录，不要直接在已有业务项目里试。目录结构可以这样：

json-module-demo/ index.html main.js data.json

data.json里放一些简单内容：

{ "title": "hello json module", "list": [1, 2, 3], "nested": { "enabled": true } }

main.js里写静态导入：

import data from './data.json' with { type: 'json' }; console.log('json module title:', data.title); console.log('json module list:', data.list); console.log('nested enabled:', data.nested.enabled);

index.html负责引入模块：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <title>JSON Module Demo</title> </head> <body> <script type="module" src="./main.js"></script> </body> </html>

这里的关键是<script type="module">。没有这一步，模块语法不会进入浏览器模块加载流程。

4.2 启动一个本地静态服务器，不要直接双击 HTML

在浏览器里直接打开index.html，大多时候会看到控制台报 CORS 错误。因为 JSON 模块的加载请求同样遵守浏览器同源策略。

启动静态服务器的方式有很多，我一般优先用 Node 命令：

npx serve .

或者直接用 Python 起一个：

python3 -m http.server 8080

启动后访问http://localhost:8080。打开开发者工具，切到 Console 面板，正常情况下会看到 three 条输出：

json module title: hello json module json module list: [1, 2, 3] nested enabled: true

如果看到的是红色的模块加载失败，不要急着改代码，先做下面两步：

• 打开 Network 面板，看data.json请求是否发送成功，状态码是不是 200。
• 看响应头里Content-Type是不是application/json。

这两个都是 JSON 模块加载最常见的拦截点。

4.3 验证成功状态：控制台、Network、Sources

控制台有输出，只代表当前用例跑通了。要让这个案例真正可靠，还需要从三个维度验证。

第一，Network 面板里能看到data.json的请求，并且状态为 200。如果请求根本没有发出去，说明模块路径或导入语法存在问题。如果请求发出去了但状态是 304 或 200 以外的状态，需要看资源是否被服务端正确处理。

第二，MIME 类型正确。点击data.json请求，查看 Response Headers 里的Content-Type。如果值是application/json; charset=utf-8这类，就是正常的。如果变成了text/plain，服务器配置有问题，模块加载器可能拒绝执行。

第三，Sources 面板里可以看到这个 JSON 被当作模块记录加载。不同浏览器显示方式不同，但一般你会看到文件树里有data.json节点，这说明浏览器已经把它纳入了模块图，而不只是一个普通静态资源。

如果这三项都通过，这个最小示例才算真正稳定。

4.4 动态导入与多个 JSON 文件的批量载入

静态导入适合在文件顶部直接声明依赖。但有时候你希望点某个按钮时再加载配置，或者根据当前语言加载对应文案，这时候动态导入更合适。

动态导入 JSON 模块的写法如下：

const locale = 'zh-CN'; const messages = await import(`./locales/${locale}.json`, { with: { type: 'json' } }); console.log(messages.default);

注意动态导入返回的模块对象里，默认导出还是在.default字段上。

如果需要同时加载多个 JSON 模块，可以配合Promise.all：

const files = [ './config/app.json', './config/routes.json', ]; const modules = await Promise.all( files.map((file) => import(file, { with: { type: 'json' } })) ); const appConfig = modules[0].default; const routesConfig = modules[1].default;

在这个阶段，你就会开始直面批量任务的问题：一个文件失败，整个Promise.all都会失败。后面第 5 章会专门展开。

5. 工程化落地：接口、批量、错误处理与参数取舍

5.1 把 JSON 模块当配置使用时，先接受一个边界

浏览器原生 JSON 模块很适合用来加载静态配置，但它不等于“运行时配置中心”。配置文件一旦进入模块加载流程，路径和内容是构建期或首次请求时就确定下来的。你在页面运行后去修改服务器上的 JSON 文件，浏览器不会自动重新加载，除非你刷新页面或重新触发动态 import。

所以我在工程化落地时会做一个区分：

• 静态业务配置，比如不经常改的图标映射、表单项类型、固定枚举值，适合用 JSON 模块导入。
• 运营可改配置、服务端下发的动态参数、需要响应后端变化的配置，更适合用 fetch 接口拉取。

像 i18n 文案这种内容，如果你接受“发布时一起更新语言包”，也可以用 JSON 模块。每个语言维护一个独立 JSON 文件，然后动态导入对应语言：

const lang = getCurrentLang(); try { const messages = await import(`./lang/${lang}.json`, { with: { type: 'json' } }); renderMessages(messages.default); } catch (error) { console.error('load language file failed:', error); loadFallbackLanguage(); }

这种写的频率不高，但如果你的页面里真的使用动态 import 变量路径，就要额外留意浏览器是否会把所有可能的 JSON 文件预取出来。现代浏览器和打包器在分析动态 import 时，对字符串模板路径的处理策略并不完全一致，实际效果要以网络请求为准。

5.2 批量加载与失败重试策略

到了批量场景，问题会比单文件复杂得多。我先举个最常见的例子：你想一次性加载多个模块，同时希望一个失败不要影响其他文件输出。

如果直接用：

const result = await Promise.all( files.map((file) => import(file, { with: { type: 'json' } })) );

只要有一个文件路径写错、内容不是标准 JSON、服务器返回非 200 状态，整个 Promise 都会 reject，你拿不到其他成功文件的任何结果。

更稳妥的方案是使用Promise.allSettled，它会把每个任务的 fulfilled 或 rejected 状态都收集起来：

const results = await Promise.allSettled( files.map((file) => import(file, { with: { type: 'json' } }) .then((mod) => ({ file, data: mod.default })) .catch((error) => ({ file, error })) ) ); results.forEach((item) => { if (item.status === 'fulfilled') { console.log(item.value.file, item.value.data); } else { console.error(item.reason.file, item.reason.error); } });

这种写法适合“能加载多少就加载多少，失败的文件单独记录”的批量任务。

如果你需要的是更完整的失败重试逻辑，建议不要直接在 import 语法外面写循环重试，而是先检查失败原因。动态 import 的返回错误信息通常不够具体，常见只告诉你模块解析失败。这时代码层面能做的判断有限，应该回到 Network 面板看具体请求，确认是 404、500、MIME 不对还是 JSON 语法错误。

如果是文件内容错误，重试多少次都一样，应该修改文件或更换路径。如果是网络临时抖动导致失败，重试才有意义。

5.3 降级方案：从with到assert，再回到 fetch

实际接手项目时，代码要兼容的浏览器可能不止一个。面对不支持新语法的环境，需要准备降级方案。

思路按优先级排序：

第一优先级，直接用with语法，前提是目标浏览器支持 import attributes 的新写法。这是最干净的方式，代码和规范保持一致。

第二优先级，如果目标环境只支持旧版assert关键字，可以在兼容范围内使用旧写法。不过建议不要长期保留这种写法，因为规范方向已经转向with，旧写法属于过渡方案。

第三优先级，如果浏览器既不支持with也不支持assert，那就退回 fetch：

async function loadJsonModule(url) { const response = await fetch(url); if (!response.ok) { throw new Error(`fetch failed: ${response.status}`); } return response.json(); }

降级方案不需要做得很复杂，关键是可以在代码里封装一个统一入口。在支持原生 JSON 模块的浏览器里动态 import，在不支持的浏览器里走 fetch，这样业务代码可以不感知底层差异。

不过实际工程里，如果一个项目本身就会经过打包器编译，我更建议把这个问题交给构建工具去处理，而不是在浏览器运行时做复杂的特性探测和降级。因为打包器可以在构建期直接识别 JSON 资源，即使目标浏览器不支持原生 JSON 模块，也能通过编译把 JSON 内容内联成 JS 模块。

6. 常见报错与排查链路

6.1 先看现象，再分网络层和语法层

遇到问题先不要急着改代码。把报错分成两类：一类是模块加载失败，另一类是模块解析失败。

模块加载失败，通常表现为 Network 面板里没有请求发出，或者请求状态不是 200。这种情况优先检查路径、服务器配置、CORS 和浏览器是否真的发起了这个请求。

模块解析失败，通常表现为请求已经发出，状态也是 200，但报错信息里带有 Unexpected token、Expected property name、JSON.parse 之类的关键词。这种情况说明文件已经拿到，但内容没有通过 JSON.parse 校验，或者在模块加载阶段没有被正确识别为 JSON 模块。

这两类问题的排查链路完全不同。先看请求有没有发出去，再看响应内容是否合法，最后才轮到 import 语法本身。

6.2 错误信息与常规处理对照表

下面是我在实际测试中比较常见的错误信息和处理方向，你可以把它当排查起点。

这只是一个查找方向，不代表绝对结论。每个项目环境不同，最终还是要回到实际日志和网络请求里判断。

6.3 部署后的排查顺序

本地能跑通，部署到线上后反而报错，这种情况很常见。我在排查线上问题时通常按下面顺序来。

第一，看控制台有没有模块加载失败。如果部署环境是 CDN，文件路径可能带哈希值或者不同前缀，需要确认 import 里写的相对路径在最终产物里是否仍然成立。

第二，看资源请求的Content-Type。线上服务器或 CDN 有可能没有正确配置.json后缀的 MIME 类型。尤其当你把 JSON 文件放在某些对象存储或自建下载服务后面时，响应头类型可能变成application/octet-stream，这会导致模块加载失败。

第三，看是否真的走到了新语法。如果项目经过构建器编译，但又没有正确配置目标浏览器的支持范围，某些工具会把 import attributes 语法原样保留，也可能把它们删除掉。这些都会导致线上行为和本地源码表现不一致。

第四，看有没有混合使用模块缓存。浏览器对模块资源的缓存策略和普通静态资源有区别，线上更新版本后，老用户可能还会请求到旧的 JSON 模块。此时需要通过文件名变化或版本参数来强制刷新，比如给 JSON 文件加内容哈希。

排查时保持一个原则：先看网络，再看解析，最后看语法。这个顺序能帮你过滤掉绝大多数低级错误。

7. 我的实际使用建议

7.1 第一批场景：静态配置、i18n、mock 数据

如果你准备在真实项目里尝试浏览器原生 JSON 模块导入，我建议从这三类场景开始。

第一类是静态配置。比如组件库的主题配置、图表图例映射、按钮权限码列表。这些内容变化频率低，依赖关系固定，放在 JSON 模块里能减少一层异步请求处理。

第二类是 i18n 文案。每个语言一个 JSON 文件，通过动态 import 按需加载，页面刷新后重新加载对应语言包。这种方式配合 import attributes 写起来很直观，但要注意目标浏览器是否支持对应语法。

第三类是本地 mock 数据。开发阶段需要页面展示测试数据时，直接用 JSON 模块代替 fetch mock 服务，可以让页面加载路径更短，也更容易被构建器统一分析。

先在这些低风险场景里跑通，再逐步考虑是否推广到更多业务模块。

7.2 不要急着替代 fetch

虽然 JSON 模块导入用起来很方便，但它不是 fetch 的替代品，也不应该成为首选方案。

fetch 的优势在于：可以动态拼接 URL、可以携带请求头、可以拿到状态码和错误信息、可以做超时控制、可以处理跨域接口、可以读取实时数据。这些能力 JSON 模块导入都不具备，或者说实现起来会非常别扭。

我的判断标准很简单：如果数据是静态的、随模块依赖关系走的，优先用 JSON 模块。如果数据是动态的、需要运行时请求的，就继续用 fetch。两者并存并不冲突，反而是最稳定的工程组合。

7.3 从浏览器原生 JSON 模块导入想到的工程化习惯

最后一个建议，也是我觉得更重要的点：每接触一个新原生特性，都应该留一部分精力去关注它背后的规范变化和使用边界。就像 JSON 模块导入从assert调整到with，如果你只记住了一段代码，大概率会在某次升级后被语法变化卡住。

真正实用的做法是：

• 写最小示例验证当前环境是否支持。
• 记录这个特性在当前项目里的适用场景和限制。
• 为不支持的环境准备退化方案。
• 在团队成员踩坑之前，把这些结论沉淀到项目文档或注释里。

浏览器原生 JSON 模块导入值得学习，也值得在一些静态数据场景里去用，但它离“默认替代 fetch”还有距离。我的建议是先把单文件跑稳，确认浏览器版本和服务器响应头都没问题之后，再考虑批量加载、i18n 按需加载和构建器集成。踩过一轮之后你会发现，很多报错并不是 JSON 模块本身的问题，而是路径、MIME 类型和语法版本没有对齐。把这些前置条件处理好，这个新特性用起来才会真的顺手。