浏览器端怎么用Fetch API读取本地JSON文件

在前端网页开发中，使用 Fetch API 获取并解析本地 JSON 数据是非常基础且高频的操作。要成功读取本地 JSON 文件，核心并不单单是调用一段 fetch('./data.json') 代码，而在于必须让网页运行在一个本地 HTTP 服务器环境中，而不是直接双击 HTML 文件通过 file:// 协议打开。本文将详细讲解这一机制的原因、具体操作步骤、异步请求代码规范及常见问题排查。

一、为什么双击打开 HTML 会读取失败？

很多初学者在写完 HTML 和 JSON 文件后，直接在操作系统文件管理器中双击 index.html 打开网页（此时浏览器地址栏以 file:/// 开头），接着便会在浏览器控制台（F12）看到类似如下报错：

Access to fetch at 'file:///path/to/data.json' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, data, isolated-app, chrome-extension, chrome, https, chrome-untrusted.

这是现代浏览器的安全沙箱机制与同源策略（SOP）所致。对于本地直接打开的 file:// 协议，浏览器的 Origin 被设定为 null，或者将每一个本地文件视为一个完全隔离的独立来源。为了防止恶意网页在未经用户授权的情况下静默扫描和窃取用户本地硬盘上的敏感数据，浏览器默认禁止了 file:// 协议下的异步资源请求（Fetch 或 XMLHttpRequest）。

二、启动本地静态服务器的方法

解决跨域与协议限制的最正规方案，就是在项目根目录启动一个轻量级本地静态 HTTP 服务。无论使用哪个开发工具，都可以一键完成：

• 方法 1：VS Code 的 Live Server 插件（最推荐）
  在 VS Code 插件市场搜索并安装 Live Server。安装后，右键点击 index.html，选择 "Open with Live Server"，浏览器会自动打开 http://127.0.0.1:5500/index.html。
• 方法 2：Python 内置简易 HTTP 服务
  无需安装额外软件，在项目根目录打开终端运行：

  # Python 3
  python -m http.server 8000

  随后在浏览器中访问 http://localhost:8000 即可。
• 方法 3：Node.js 环境使用 npx serve
  如果本机已安装 Node.js，直接在项目目录下运行：

  npx serve .

三、核心代码：使用 Fetch 读取本地 JSON

Fetch API 是现代浏览器原生支持的基于 Promise 的异步网络请求接口。读取 JSON 文件的过程分为两阶段：先获取响应流（Response），再将响应体反序列化为 JavaScript 对象。

1. 项目文件组织

假定项目目录结构如下：

my-project/
├── index.html
├── app.js
└── data.json

data.json 中的测试内容如下（必须符合标准 JSON 语法，属性名必须使用双引号）：

{
  "siteName": "前端实用教程",
  "version": "1.0.0",
  "articles": [
    { "id": 1, "title": "Fetch API 快速入门" },
    { "id": 2, "title": "理解同源策略与跨域" }
  ]
}

2. async/await 推荐写法与双阶段解析

在 app.js 中编写读取代码。推荐采用 async/await 配合 try...catch，结构清晰且易于进行错误处理：

// 异步读取本地 JSON 文件的完整示例
async function loadLocalJson() {
  const url = './data.json'; // 本地相对路径
  
  try {
    // 阶段 1：发送请求获取 Response 对象
    const response = await fetch(url);
    
    // 关键校验：检查 HTTP 状态码是否在 200-299 范围内
    if (!response.ok) {
      throw new Error(`HTTP 状态错误，状态码: ${response.status} (${response.statusText})`);
    }
    
    // 阶段 2：异步读取流并解析为 JSON 对象
    const data = await response.json();
    
    // 阶段 3：成功获取数据后的业务处理
    console.log('读取到的 JSON 数据:', data);
    renderData(data);
    
  } catch (error) {
    // 捕获网络失败、404、或 JSON 格式非法等各种错误
    console.error('读取或解析本地 JSON 失败:', error.message);
  }
}

function renderData(data) {
  document.getElementById('site-name').textContent = data.siteName;
}

// 页面加载完成后调用
window.addEventListener('DOMContentLoaded', loadLocalJson);

四、常见问题排查与避坑要点

五、补充场景：用户本地直接选择文件读取

如果业务需求是让用户在自己的电脑中随意选择一个外部 JSON 文件，并在浏览器端读取其内容，此时无需搭建本地 HTTP 服务，而是应该配合 HTML 的文件上传控件 <input type="file">，利用 Blob 或 File API 进行解析：

// 监听文件选择框
const fileInput = document.getElementById('json-file-picker');

fileInput.addEventListener('change', async (event) => {
  const file = event.target.files[0];
  if (!file) return;

  // 现代方式：直接调用 File 对象的 .text() 方法获取文本，再反序列化
  try {
    const textContent = await file.text();
    const data = JSON.parse(textContent);
    console.log('读取用户本地选择的 JSON:', data);
  } catch (err) {
    console.error('解析所选文件失败，请检查文件格式:', err);
  }
});

或者，如果依然希望统一使用 Fetch API 的接口风格，也可以通过 URL.createObjectURL(file) 生成临时内存引用：

// 转换为 blob URL 后通过 fetch 统一读取
const blobUrl = URL.createObjectURL(file);
const res = await fetch(blobUrl);
const data = await res.json();
URL.revokeObjectURL(blobUrl); // 释放内存引用

六、总结

在浏览器端使用 Fetch API 读取本地 JSON 文件的关键可以概括为两点：运行机制上必须依靠本地 HTTP 静态服务器（如 Live Server）来提供符合同源策略的运行上下文；代码实现上则需遵守 Fetch API 的双阶段异步处理规范，结合 response.ok 判断与 try...catch 异常捕获。遵循上述开发规范，即可在前端开发过程中稳定、可靠地读取和解析各类本地 JSON 数据资源。