本文介绍一种基于 promise 缓存与模块化设计的方案，实现对大型 json 文件（如含 5 万+ 条记录的 data.json）的一次性异步加载，并在全站任意脚本中安全、同步地访问已解析数据，避免重复请求与作用域问题。
本文介绍一种基于 promise 缓存与模块化设计的方案，实现对大型 json 文件（如含 5 万+ 条记录的 data.json）的一次性异步加载，并在全站任意脚本中安全、同步地访问已解析数据，避免重复请求与作用域问题。
在前端开发中，当需要将一个大型静态 JSON 文件（例如 data.json，含数万条结构化记录）作为全局数据源供多个组件或页面逻辑使用时，关键挑战在于：既要保证只发起一次网络请求，又要确保后续任意位置都能可靠、同步地获取已解析的数据。你当前遇到的 dataset is not defined 或 console.log(dataset.length) 返回 undefined 的问题，本质是典型的异步时序错误——浏览器执行 <script> 中的同步代码时，fetch 还未完成，data 变量根本不存在于全局作用域，且 JavaScript 没有“自动等待”异步操作完成的机制。</script>
✅ 推荐方案：封装为可复用的「数据加载器」（Data Loader）
我们不依赖全局变量（易污染、难维护），而是创建一个返回 Promise 的模块化函数。该函数内部自动缓存首次加载结果，后续调用直接返回已解析的 Promise，真正实现「一次加载，处处可用」：
1. 创建 dataLoader.js（推荐放在 js/ 目录下）
// js/dataLoader.js
let cachedDataPromise = null;
export function loadDataset() {
if (!cachedDataPromise) {
cachedDataPromise = fetch('./data.json') // 注意路径：假设 data.json 与 HTML 同级或按需调整
.then(response => {
if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
return response.json();
})
.catch(err => {
console.error('❌ 数据加载失败:', err);
throw err;
});
}
return cachedDataPromise;
}
✅ 优势说明：
- cachedDataPromise 在首次调用后被赋值，后续调用直接返回该 Promise（不会重新 fetch）；
- 使用 export 支持 ES 模块导入，现代浏览器原生支持；
- 内置错误处理，避免静默失败；
- 路径 ./data.json 需根据实际部署结构调整（如放在 /js/data.json 则改为 ./js/data.json）。
2. 在 HTML 中正确使用（index.html）
<meta charset="UTF-8"><title>Data Table Demo</title><h1>File Active — Data Loading Test</h1>
<!-- ✅ 正确方式：使用 type="module" 导入并使用 -->
<script type="module">
import { loadDataset } from './js/dataLoader.js';
// ✅ 任何时候调用都安全：首次加载，后续秒取
loadDataset()
.then(data => {
console.log(`✅ 成功加载 ${data.length} 条记录`);
// ? 此处可初始化表格、渲染图表、过滤数据等
renderTable(data); // 示例函数（见下方）
})
.catch(err => {
console.error('⚠️ 页面初始化失败:', err);
});
// 示例：另一个需要数据的逻辑（比如搜索框初始化）
document.addEventListener('DOMContentLoaded', () => {
loadDataset().then(data => {
console.log(`? 搜索功能已就绪，共 ${data.length} 条可检索数据`);
});
});
</script><!-- ✅ 如需在非模块脚本中使用（兼容旧环境），可暴露全局方法 --><script>
// ⚠️ 仅作兼容性补充（不推荐主逻辑用）
window.getDataset = async function() {
const { loadDataset } = await import('./js/dataLoader.js');
return loadDataset();
};
</script>
3. 示例：快速渲染为 HTML 表格（renderTable 实现）
// 在上面的 <script type="module"> 内追加：
function renderTable(data) {
const table = document.createElement('table');
table.innerHTML = `
<thead><tr>
<th>部门<th>日期<th>姓名<th>项目<th>工时
<tbody>
`;
data.slice(0, 5).forEach(item => { // 仅渲染前5行示例
const row = table.querySelector('tbody').insertRow();
row.insertCell().textContent = item.Department;
row.insertCell().textContent = item.Date;
row.insertCell().textContent = item.Name;
row.insertCell().textContent = item.Project;
row.insertCell().textContent = item.Time;
});
document.body.appendChild(table);
}</script>
⚠️ 重要注意事项
- 路径必须准确：fetch('./data.json') 中的路径需与服务器实际文件位置一致。若 data.json 在 js/ 目录下，请写 ./js/data.json；若在根目录，则用 /data.json（绝对路径更稳定）。
- CORS 限制：本地双击打开 HTML 会因浏览器 CORS 策略导致 fetch 失败。请使用 live-server、VS Code Live Server 插件，或部署到 HTTP 服务（如 Nginx、Vercel）下测试。
- 内存考量：5 万+ 条 JSON 记录在内存中约占用几 MB —— 现代浏览器完全可承受，但若后续需分页/搜索，建议配合 Array.prototype.filter() 或客户端数据库（如 Dexie.js）进一步优化。
- 不要混用 type="module" 和传统脚本：你原代码中 <script src="js/hscript.js"> 与 <script type="module"> 混用会导致作用域隔离，hscript.js 中的变量无法被外部 <script> 访问 —— 这正是问题根源。统一使用 ES 模块是现代最佳实践。</script>
✅ 总结
通过将数据加载逻辑封装为带缓存的 Promise 工厂函数（loadDataset()），我们彻底解决了「异步时机不可控」和「全局变量不可靠」两大痛点。它轻量、无依赖、符合标准，且天然支持 await 语法（如 const data = await loadDataset()），为构建高性能、可维护的数据驱动型网站打下坚实基础。
