当前位置：首页 > 文章列表 > 文章 > 前端 > Node.js文件读写入门指南

Node.js文件读写入门指南

2025-09-19 18:22:32 0浏览收藏

Node.js文件操作是构建高性能服务器端应用的关键技能。本文将深入讲解Node.js内置的fs模块，助你掌握文件读写技巧。核心在于理解并运用fs模块提供的异步API（如`fs.readFile`和`fs.writeFile`），避免阻塞事件循环，提升应用响应速度。对于大文件处理，应采用`fs.createReadStream`和`fs.createWriteStream`进行流式操作，配合`pipe`方法实现高效的数据传输和内存优化。此外，本文还将着重强调文件路径处理的重要性，推荐使用`path.join(__dirname, ...)`构建跨平台兼容的绝对路径，并通过`fs.access`检查文件权限，预防常见的EACCES错误。掌握这些技巧，你就能编写出健壮、高效的Node.js文件处理代码。

Node.js文件操作核心是fs模块，推荐使用异步API避免阻塞事件循环。常用方法包括fs.readFile/writeFile进行异步读写，fs.readFileSync/writeFileSync用于同步场景（如配置加载），大文件处理应使用fs.createReadStream/writeStream流式操作以节省内存，配合pipe实现高效传输。路径处理需用path.join(__dirname, ...)确保跨平台兼容，权限问题可通过fs.access检查，避免EACCES错误。异步非阻塞模式是最佳实践。

怎样使用Node.js读写文件？

Node.js在文件读写方面，核心就是利用其内置的fs（File System）模块。这个模块提供了丰富的API，既有同步（*Sync后缀）也有异步（回调函数或Promise）版本，让你能够灵活地处理文件操作。通常，我们更倾向于使用异步API，因为它不会阻塞Node.js的事件循环，保持应用的响应性。

解决方案

在Node.js中进行文件读写，最直接的方式就是通过fs模块。下面我来详细拆解一下常用的几种方法。

读取文件：

最常见的读取文件方式是使用fs.readFile()或fs.readFileSync()。

异步读取 (fs.readFile)： 这是我个人最推荐的方式，尤其是在服务器环境中。它不会阻塞主线程，让你的应用保持高效。

const fs = require('fs');
const path = require('path');

const filePath = path.join(__dirname, 'example.txt'); // 假设文件在当前目录下

fs.readFile(filePath, 'utf8', (err, data) => {
    if (err) {
        console.error('读取文件时发生错误:', err);
        // 这里可以根据错误类型做进一步处理，比如文件不存在、权限问题等
        return;
    }
    console.log('异步读取到的内容:', data);
});

// 也可以使用Promise/async-await模式，代码会更现代和易读
const util = require('util');
const readFilePromise = util.promisify(fs.readFile);

async function readMyFile() {
    try {
        const data = await readFilePromise(filePath, 'utf8');
        console.log('Async/Await 读取到的内容:', data);
    } catch (err) {
        console.error('Async/Await 读取文件时发生错误:', err);
    }
}
readMyFile();

这里我用了path.join来构建文件路径，这是一个好习惯，可以避免不同操作系统路径分隔符的问题。

同步读取 (fs.readFileSync)： 虽然代码看起来更简洁，但它会阻塞Node.js进程，直到文件完全读取完毕。这意味着在文件读取期间，你的应用无法处理其他请求。我通常只在启动脚本、配置加载等非核心业务逻辑中偶尔使用它。

const fs = require('fs');
const path = require('path');

const filePath = path.join(__dirname, 'example.txt');

try {
    const data = fs.readFileSync(filePath, 'utf8');
    console.log('同步读取到的内容:', data);
} catch (err) {
    console.error('同步读取文件时发生错误:', err);
    // 记得处理错误，否则程序可能会崩溃
}

写入文件：

写入文件同样有异步的fs.writeFile()和同步的fs.writeFileSync()。

异步写入 (fs.writeFile)： 这是写入文件的首选方式。如果文件不存在，它会创建文件；如果文件已存在，它会覆盖原有内容。

const fs = require('fs');
const path = require('path');

const filePath = path.join(__dirname, 'output.txt');
const content = '这是要写入文件的新内容。\nNode.js文件操作真有趣！';

fs.writeFile(filePath, content, 'utf8', (err) => {
    if (err) {
        console.error('写入文件时发生错误:', err);
        return;
    }
    console.log('文件异步写入成功！');
});

// 同样可以Promise化
const writeFilePromise = util.promisify(fs.writeFile); // util在上面已经引入

async function writeMyFile() {
    try {
        await writeFilePromise(filePath, '这是通过Async/Await写入的内容。', 'utf8');
        console.log('Async/Await 文件写入成功！');
    } catch (err) {
        console.error('Async/Await 写入文件时发生错误:', err);
    }
}
writeMyFile();

同步写入 (fs.writeFileSync)： 和同步读取一样，它会阻塞进程。

const fs = require('fs');
const path = require('path');

const filePath = path.join(__dirname, 'output_sync.txt');
const content = '这是通过同步方式写入的内容。';

try {
    fs.writeFileSync(filePath, content, 'utf8');
    console.log('文件同步写入成功！');
} catch (err) {
    console.error('同步写入文件时发生错误:', err);
}

追加内容 (fs.appendFile / fs.appendFileSync)： 如果你不想覆盖原有内容，而是想在文件末尾追加，可以使用appendFile。

const fs = require('fs');
const path = require('path');

const filePath = path.join(__dirname, 'log.txt');
const newLogEntry = `\n[${new Date().toISOString()}] 用户访问记录。`;

fs.appendFile(filePath, newLogEntry, 'utf8', (err) => {
    if (err) {
        console.error('追加内容时发生错误:', err);
        return;
    }
    console.log('内容已成功追加到文件。');
});

异步与同步：我该如何选择Node.js文件操作模式？

这是一个老生常谈但又极其重要的问题，尤其是在Node.js这种单线程、事件驱动的环境里。我的经验是，绝大多数情况下，你都应该优先选择异步操作。

Node.js的核心优势在于其非阻塞I/O模型。当你的代码执行一个异步文件操作（比如fs.readFile）时，它会立即将这个任务交给操作系统，然后Node.js的事件循环会继续处理其他事情（比如响应另一个HTTP请求）。一旦文件操作完成，操作系统会通知Node.js，然后Node.js会通过回调函数或Promise来处理结果。这种模式让你的服务器能够同时处理大量的并发请求，而不会因为等待文件I/O而“卡住”。

想象一下，如果你的Web服务器在处理每个文件请求时都使用同步操作，那么当一个用户请求一个大文件时，其他所有用户的请求都必须排队等待，直到这个大文件完全读取完毕。这显然是不可接受的，用户体验会非常糟糕。

那么，同步操作就一无是处了吗？也不是。在一些特定的场景下，同步操作反而能让代码逻辑更简单，更直观。例如：

应用启动时加载配置： 在应用启动阶段，你需要读取一些配置信息才能继续运行。此时，阻塞几毫秒读取一个小的JSON文件通常是可接受的，因为此时还没有用户请求需要处理。使用同步方式可以避免复杂的异步流程，确保配置在应用逻辑开始前就位。
一次性脚本或工具： 如果你写一个命令行工具，只是简单地读写几个文件，没有并发需求，同步代码可能会让你写起来更快，也更容易理解。
必须在当前上下文完成的操作： 极少数情况下，某个操作的结果必须立即可用，并且你确定它不会对性能造成显著影响。

即便如此，我仍然建议你对同步操作保持警惕。即使是小的文件，在极端高并发或资源受限的环境下，也可能成为性能瓶颈。养成使用异步的习惯，能让你在项目规模扩大时少走很多弯路。

处理大文件：Node.js流（Stream）的魅力与实践

当我们谈到读写大文件时，fs.readFile和fs.writeFile就不那么理想了。为什么？因为它们会尝试一次性将整个文件内容加载到内存中。如果你的文件有几个GB，你的服务器内存可能根本吃不消，轻则应用崩溃，重则影响整个系统稳定性。

这时候，Node.js的流（Stream）就闪亮登场了。流的理念是：数据不是一次性全部处理，而是以小块（chunks）的形式流动。你可以从一个流中读取数据，处理后，再写入另一个流。这就像水管一样，水（数据）在管道中持续流动，而不是先装满一个大桶再倒到另一个大桶。

流的优势：

内存效率： 只在内存中保留当前处理的数据块，而不是整个文件。
时间效率： 一旦有数据块可用，就可以立即开始处理，无需等待整个文件传输完成。
可组合性： 流可以很容易地通过pipe()方法连接起来，形成一个处理管道，非常优雅。

实践：使用fs.createReadStream和fs.createWriteStream

读取大文件：fs.createReadStream(path, [options])会返回一个可读流（Readable Stream）。

const fs = require('fs');
const path = require('path');

const bigFilePath = path.join(__dirname, 'big_file.txt'); // 假设这是一个大文件

const readStream = fs.createReadStream(bigFilePath, { encoding: 'utf8', highWaterMark: 64 * 1024 }); // highWaterMark设置缓冲区大小

let totalChunks = 0;
let totalSize = 0;

readStream.on('data', (chunk) => {
    totalChunks++;
    totalSize += chunk.length;
    // console.log(`接收到数据块 (${chunk.length} 字节):`, chunk.substring(0, 50), '...');
    // 这里你可以对每个数据块进行处理
});

readStream.on('end', () => {
    console.log(`大文件读取完毕。总共接收了 ${totalChunks} 个数据块，总大小 ${totalSize} 字节。`);
});

readStream.on('error', (err) => {
    console.error('读取大文件时发生错误:', err);
});

写入大文件：fs.createWriteStream(path, [options])会返回一个可写流（Writable Stream）。

const fs = require('fs');
const path = require('path');

const outputFilePath = path.join(__dirname, 'copied_big_file.txt');
const writeStream = fs.createWriteStream(outputFilePath, { encoding: 'utf8' });

// 我们可以模拟一些数据写入
for (let i = 0; i < 100000; i++) {
    writeStream.write(`这是第 ${i} 行模拟数据，用于测试大文件写入。\n`);
}

writeStream.end(() => {
    console.log('大文件模拟写入完成。');
});

writeStream.on('error', (err) => {
    console.error('写入大文件时发生错误:', err);
});

流的管道（Piping）：复制大文件 流最强大的地方在于它的pipe()方法。你可以直接将一个可读流连接到一个可写流，数据就会自动从源流传输到目标流，无需手动处理每个数据块。这对于复制文件、文件上传下载等场景非常有用。

const fs = require('fs');
const path = require('path');

const sourceFilePath = path.join(__dirname, 'big_file.txt');
const destinationFilePath = path.join(__dirname, 'big_file_copy.txt');

const readStream = fs.createReadStream(sourceFilePath);
const writeStream = fs.createWriteStream(destinationFilePath);

readStream.pipe(writeStream); // 一行代码搞定文件复制

readStream.on('error', (err) => {
    console.error('复制过程中读取文件失败:', err);
});

writeStream.on('error', (err) => {
    console.error('复制过程中写入文件失败:', err);
});

writeStream.on('finish', () => {
    console.log('大文件复制完成！');
});

使用流处理大文件是Node.js中非常高效且优雅的解决方案，它能让你轻松应对那些动辄几十上百兆，甚至更大的文件。

文件路径与权限：Node.js文件操作中常见的坑与解法

在Node.js中进行文件操作，除了API本身，最常让我头疼的，往往是文件路径和权限问题。这些问题看起来琐碎，但一旦出错，调试起来可能让人抓狂。

1. 文件路径的迷思：相对路径与绝对路径

相对路径： 在开发时我们经常使用./data/config.json这样的相对路径。但在Node.js环境中，相对路径是相对于process.cwd()（即当前工作目录）解析的，而不是相对于你的脚本文件所在的目录。这可能会导致一个常见的问题：如果你在项目的根目录运行node src/app.js，而app.js中尝试读取./data/config.json，那么它会在项目根目录寻找data文件夹，而不是src目录下的data。
绝对路径： 避免这种混乱的最佳实践是使用绝对路径。Node.js提供了几个非常有用的全局变量和模块来帮助你构建可靠的绝对路径：
- __dirname： 总是返回当前执行的脚本文件所在的目录的绝对路径。
- __filename： 总是返回当前执行的脚本文件的绝对路径。
- path模块： 这是处理文件路径的瑞士军刀。
  - path.join()：安全地连接路径片段，它会自动处理不同操作系统的路径分隔符（Windows是\，Linux/macOS是/）。
  - path.resolve()：将一系列路径或路径片段解析为绝对路径。
示例：构建可靠的路径
```
const path = require('path');

// 获取当前脚本文件所在目录的绝对路径
const currentDir = __dirname;
console.log('当前脚本目录:', currentDir);

// 构建一个相对于当前脚本目录的data文件夹下的config.json的绝对路径
const configPath = path.join(currentDir, 'data', 'config.json');
console.log('配置文件的绝对路径:', configPath);

// 如果想获取项目根目录下的文件，可能需要向上跳几级
// 假设你的脚本在 project/src/utils/file_ops.js
// 项目根目录就是 path.resolve(__dirname, '..', '..')
const projectRoot = path.resolve(__dirname, '..'); // 假设当前脚本就在项目根目录的子目录
console.log('项目根目录:', projectRoot);
```
我强烈建议你在任何需要引用文件的地方，都使用path.join(__dirname, ...)来构建绝对路径。这能极大地减少“文件找不到”的奇葩问题。

2. 权限问题：EACCES错误

当你尝试读写一个文件或目录，但你的Node.js进程没有足够的权限时，你会遇到EACCES（Permission denied）错误。这在部署到服务器上时尤为常见。

Linux/macOS：
- 用户和组： 文件和目录都有所有者、所属组以及对应的权限（读r、写w、执行x）。
- chmod： 你可以使用chmod命令来修改文件或目录的权限。例如，chmod 644 myfile.txt表示所有者可读写，组用户和其他用户只可读；chmod 777 mydir表示所有人对目录都有读写执行权限（通常不推荐，过于开放）。
- chown： 你可以使用chown命令来修改文件或目录的所有者。
- 进程用户： 确保运行Node.js进程的用户（例如，www-data用户在Nginx/Apache下）对目标文件或目录拥有必要的读写权限。
Windows：
- Windows使用ACL（Access Control List）来管理权限，通常通过文件属性的安全选项卡进行配置。确保运行Node.js进程的用户账户（或服务账户）有权访问目标文件或目录。

Node.js中的权限检查：fs.access() 在进行实际的文件操作之前，你可以使用fs.access()来异步检查文件或目录的权限。

const fs = require('fs');
const path = require('path');

const testFilePath = path.join(__dirname, 'test_permission.txt');

// 假设我们想检查文件是否存在且可写
fs.access(testFilePath, fs.constants.F_OK | fs.constants.W_OK, (err) => {
    if (err) {
        console.error(`文件 ${testFilePath} 不存在或不可写:`, err.message);
        // 可能是 ENOENT (文件不存在) 或 EACCES (权限不足)
    } else {
        console.log(`文件 ${testFilePath} 存在且可写。`);
        // 现在可以安全地进行写入操作了
        fs.writeFile(testFilePath, 'Hello, world!', (writeErr) => {
            if (writeErr) console.error('写入失败:', writeErr);
            else console.log('文件写入成功。');
        });
    }
});

处理权限问题，很多时候需要你在操作系统层面进行干预。当你在服务器上遇到EACCES错误时，第一步总是检查你的Node.js进程是以哪个用户身份运行的，然后确认那个用户对目标文件或目录是否拥有足够的权限。这往往比你想象的要简单，但容易被忽略。

今天关于《Node.js文件读写入门指南》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！

Node.js 文件路径异步操作 fs模块流