Node.js中怎么读取本地JSON文件

作者:栖木时间:2026-11-21 21:12:12浏览:415

详细介绍在 Node.js 中读取本地 JSON 文件的完整方案,对比异步 fs.promises.readFile、同步 fs.readFileSync 以及模块化加载的底层机制、适用场景、路径陷阱与异常处理规范。

在 Node.js 中读取本地 JSON 文件主要有两种处理思路:一种是将 JSON 视作纯文本数据,利用文件系统模块读取后再通过 JSON.parse() 反序列化;另一种则是把 JSON 当作模块直接加载。对于绝大多数常规开发与服务端场景,最推荐的标准做法是使用 fs/promises 的 readFile 异步读取,它既能避免阻塞主线程事件循环,又支持文件内容变动后的实时更新。
Node.js中怎么读取本地JSON文件
图 1:Node.js 本地 JSON 读取的三种主要技术路线对比

一、首选方案:使用 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();
终端示例输出
读取成功,应用名称: OrderService
配置端口: 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') 能够确保路径始终锚定在当前代码文件的物理位置。
ES Module(ESM)环境下的路径差异:
在 "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');
Node.js中怎么读取本地JSON文件
图 2:异步读取并解析本地 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);
终端示例输出
同步读取就绪,端口为: 8080

适用边界与明确警示:在服务端应用监听端口、对外提供 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' }。跨版本部署时极易因语法变动引发解析错误。
Node.js中怎么读取本地JSON文件
图 3:require() 模块缓存机制 与 fs 磁盘读取机制 的内部行为对比

四、异常处理与防御性读取封装

在生产环境下读取本地 JSON,必须考虑两类最常见的运行时异常,避免未捕获错误直接导致主进程退出:

  1. 文件不存在(ENOENT):文件路径拼写错误、文件尚未生成,或项目部署时遗漏配置。
  2. 格式语法错误(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)
Node.js中怎么读取本地JSON文件
图 4:Node.js 本地 JSON 读取方案的技术选型决策树
作者最新文章
相关文章
更多