Node.js中怎么读取本地JSON文件
详细介绍在 Node.js 中读取本地 JSON 文件的完整方案,对比异步 fs.promises.readFile、同步 fs.readFileSync 以及模块化加载的底层机制、适用场景、路径陷阱与异常处理规范。
JSON.parse() 反序列化;另一种则是把 JSON 当作模块直接加载。对于绝大多数常规开发与服务端场景,最推荐的标准做法是使用 fs/promises 的 readFile 异步读取,它既能避免阻塞主线程事件循环,又支持文件内容变动后的实时更新。
一、首选方案:使用 fs/promises 异步读取与解析
Node.js 是基于事件循环(Event Loop)的单线程异步运行环境。在处理文件 I/O 时,直接使用异步非阻塞方法能保证 Node.js 进程在等待磁盘读取期间继续处理网络请求和其他计算任务。自 Node.js 14 开始,内置的 fs/promises API 已经高度成熟,是读取本地 JSON 文件的最通用方案。
假设项目目录下存在一个待读取的数据文件 app-config.json,内容如下:
{
"appName": "OrderService",
"port": 8080,
"features": ["logging", "rateLimit"]
}
通过 fs/promises 读取并解析该文件的标准代码如下:
// 无论是在 CommonJS 还是 ES Module 中均可使用
const fs = require('fs/promises');
const path = require('path');
async function loadConfig() {
// 1. 拼接绝对物理路径,规避 cwd 漂移问题
const filePath = path.join(__dirname, 'app-config.json');
try {
// 2. 指定 'utf-8' 编码读取字符串
const rawData = await fs.readFile(filePath, 'utf-8');
// 3. 将 JSON 文本解析为 JavaScript 对象
const config = JSON.parse(rawData);
console.log('读取成功,应用名称:', config.appName);
console.log('配置端口:', config.port);
return config;
} catch (error) {
console.error('读取或解析 JSON 失败:', error.message);
throw error;
}
}
loadConfig();
配置端口: 8080
为什么必须传入 utf-8 编码与使用 path.join
在上面的代码中有两个关键细节:
- 编码参数:
fs.readFile(filePath, 'utf-8')第二个参数若省略,返回的将是原始的二进制Buffer。虽然现代 V8 引擎中的JSON.parse()也能够隐式转换 Buffer,但明确指定'utf-8'编码返回字符串可以提升代码意图可读性,并且方便在解析前打印日志或做字符串修整。 - 路径定位:永远不要直接传入相对路径(如
'./app-config.json')。在 Node.js 中,传给fs模块的相对路径是相对于当前执行命令的终端工作目录(即process.cwd()),而不是当前脚本所在的目录。一旦用户从项目的根目录或其他子目录执行node ./src/index.js,相对路径就会立即失效并抛出ENOENT错误。使用path.join(__dirname, 'app-config.json')能够确保路径始终锚定在当前代码文件的物理位置。
在
"type": "module" 的 ESM 环境中,全局变量 __dirname 默认未定义。在 Node.js 20.11.0 及以上版本中,可以直接使用原生的 import.meta.dirname;若兼容较低版本 Node.js,可以通过 fileURLToPath 手动计算:
import fs from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const filePath = path.join(__dirname, 'app-config.json');
二、轻量场景与初始化:使用 fs.readFileSync 同步读取
虽然异步是首选,但在某些特定场景下,同步读取 fs.readFileSync 具有极高的工程价值。典型的例子包括:开发命令行 CLI 工具、编写快速验证脚本,或者在服务端监听端口前(应用启动阶段)必须加载静态的初始化参数。
const fs = require('fs');
const path = require('path');
function loadConfigSync() {
const filePath = path.join(__dirname, 'app-config.json');
try {
const rawData = fs.readFileSync(filePath, 'utf-8');
return JSON.parse(rawData);
} catch (err) {
console.error('同步加载配置失败:', err.message);
process.exit(1);
}
}
// 在应用启动前执行,阻塞当前执行流直到配置就绪
const config = loadConfigSync();
console.log('同步读取就绪,端口为:', config.port);
适用边界与明确警示:在服务端应用监听端口、对外提供 HTTP/RPC 服务的生命周期内,严禁在接口路由处理函数中调用 readFileSync。同步磁盘 I/O 会将整个 Node.js 进程冻结几十到几百毫秒,在此期间其他所有用户的网络连接均无法被事件循环调度,造成并发性能断崖式下跌。
三、模块化加载辨析:require 与 import 的认知修正
在 Node.js 社区中,经常能看到一种说法:“直接用 require('./data.json') 只有一行代码,不用读文件也不用调 JSON.parse,这才是最简捷优雅的读取方式。”
这种说法并非完全错误,它在特定的限制条件下确实成立,但在复杂生产工程中却常常引发严重的副作用。我们需要全面厘清它的成立条件与潜在缺陷:
1. 它为什么看似合理且在何种条件下成立
CommonJS 规范原生支持对 .json 后缀文件的加载。当执行 const data = require('./data.json') 时,Node.js 内部会自动读取文件内容并执行反序列化,直接返回对象。如果你的文件是只读的静态常量配置(例如预置的国家代码字典、系统固定错误码表),且在整个应用运行期间绝对不会被外部文件系统更改,那么这种写法是安全且简明的。
2. 在哪些地方需要明确修正
- 模块缓存机制(Module Cache):Node.js 会在内部字典
require.cache中以文件绝对路径为键缓存模块返回值。若磁盘上的 JSON 文件被其他程序或定时任务更新,再次执行require('./data.json')只会返回第一次加载时的旧内存对象,无法获取最新内容。 - 引用对象篡改风险:
require返回的是一个普通 JavaScript 对象的内存引用。如果某个模块中的业务逻辑执行了data.port = 9000,其他任何模块随后引入该 JSON 文件时,读取到的port都会变成被篡改后的9000,导致隐蔽的全局状态污染。 - ES Module 的版本断层:在 ESM 项目中不能直接使用
require。若使用import语法加载 JSON,必须添加属性断言。在 Node.js 早期版本(16~18)使用的是assert { type: 'json' },而在现代标准及 Node.js 20+ 中已演进为with { type: 'json' }。跨版本部署时极易因语法变动引发解析错误。
四、异常处理与防御性读取封装
在生产环境下读取本地 JSON,必须考虑两类最常见的运行时异常,避免未捕获错误直接导致主进程退出:
- 文件不存在(ENOENT):文件路径拼写错误、文件尚未生成,或项目部署时遗漏配置。
- 格式语法错误(SyntaxError):JSON 文件内容被人为手动编辑时引入了末尾逗号(trailing comma)、使用了单引号、缺少闭合括号,或包含了标准 JSON 不支持的 JavaScript 注释。
我们可以将读取逻辑封装为一个健壮的防御性工具函数:
const fs = require('fs/promises');
/**
* 安全读取并解析本地 JSON 文件
* @param {string} absolutePath 绝对路径
* @param {object} fallbackDefault 当读取或解析失败时的默认值
* @returns {Promise<object>}
*/
async function safeReadJson(absolutePath, fallbackDefault = {}) {
try {
const content = await fs.readFile(absolutePath, 'utf-8');
return JSON.parse(content);
} catch (error) {
if (error.code === 'ENOENT') {
console.warn(`[ConfigWarn] 目标文件不存在: ${absolutePath},使用默认兜底配置`);
return fallbackDefault;
}
if (error instanceof SyntaxError) {
console.error(`[ConfigError] JSON 格式解析失败: ${absolutePath},错误详情: ${error.message}`);
return fallbackDefault;
}
// 其他权限(EACCES)等不可预测异常向上抛出
throw error;
}
}
五、工程选型指南与总结
综合以上分析,不同读取方式的横向比对如下表所示:
| 读取方式 | I/O 类型 | 缓存行为 | 动态更新感知 | 适用环境 | 核心推荐场景 |
|---|---|---|---|---|---|
fs.promises.readFile |
异步非阻塞 | 无缓存 | 实时生效 | CJS / ESM 通用 | 生产环境推荐:高并发 Web 服务、数据随时会变动的文件 |
fs.readFileSync |
同步阻塞 | 无缓存 | 实时生效 | CJS / ESM 通用 | 单次任务:CLI 工具、单元测试脚本、服务启动前准备 |
require('./data.json') |
同步阻塞 | require.cache 缓存 |
无法感知更新 | 仅限 CommonJS | 固化常量:项目内只读字典、固定不变的静态资源配置 |
import ... with { type: 'json' } |
异步模块加载 | 模块系统缓存 | 无法感知更新 | 需 Node 20+ 原生 ESM | 现代 ESM 模块中加载静态元数据(如读取 package.json) |
JS发送邮件报错535 Authentication failed怎么解决
2026-11-21 11:05:36
纯前端无后端依赖:JS 实现 Excel 文件导出的几种方案
2026-11-19 16:33:19
PHP中执行JavaScript代码的三种方案:v8js扩展、Node子进程与无头浏览器
2026-11-19 14:04:14
Python调用JS报错RuntimeError的常见原因及修复
2026-11-18 23:35:27
Node.js是干啥的:JavaScript后端运行环境详解
2026-11-18 22:55:29








