Node.jsでファイル名を変更する方法：fs.renameとfs.promisesを使い分ける手順

Node.jsにおいてファイル名を変更する操作は、ログファイルの整理やユーザーアップロードの処理など、バックエンド開発において非常に頻繁に発生するタスクの一つです。

Node.jsの標準ライブラリである「fs (File System)」モジュールを利用することで、直感的にファイル名の変更やディレクトリの移動を行うことができます。

本記事では、Node.jsでファイル名を変更するための主要な手法である「fs.rename」と「fs.promises.rename」の使い分け、さらに実務で役立つエラーハンドリングについて詳しく説明します。

Node.jsにおけるファイル操作の基本

Node.jsでファイルシステムを操作する場合、コアモジュールであるfsモジュールを使用するのが一般的です。

fsモジュールには、伝統的なコールバック方式、同期方式、そして現代的なPromise方式の3つのAPIが用意されています。

2026年現在のモダンな開発環境では、コードの可読性とメンテナンス性の観点から、PromiseベースのAPI（fs.promises）が主流となっています。

しかし、既存のコードベースの保守や、特定のパフォーマンス要件がある場合には、コールバック方式や同期方式を選択する場面も依然として存在します。

それぞれの方法にはメリットとデメリットがあるため、プロジェクトの要件に応じて適切な手法を選択することが重要です。

パスの指定とpathモジュールの併用

ファイル名を変更する際には、対象ファイルのパスを正確に指定する必要があります。

OSごとのパス区切り文字の違いを吸収するために、pathモジュールの使用が推奨されます。

絶対パスと相対パスのどちらでも操作は可能ですが、予期せぬディレクトリでの操作を防ぐために絶対パスを利用することが安全な開発のポイントです。

次の章からは、具体的なコード例を交えて各メソッドの実装方法を確認していきましょう。

fs.renameメソッドによる非同期処理（コールバック）

fs.renameは、Node.jsの初期から存在する伝統的な非同期メソッドです。

このメソッドは、処理が完了した際、またはエラーが発生した際に呼び出されるコールバック関数を引数に取ります。

fs.renameの基本構文

fs.renameの第一引数には現在のファイルパス、第二引数には新しいファイルパスを指定します。

第三引数には、エラーオブジェクトを受け取るコールバック関数を記述します。

このメソッドはノンブロッキングで動作するため、ファイル名の変更中もメインスレッドを停止させることがありません。

実装コード例

以下に、コールバック方式を用いた具体的な実装例を示します。

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

// 旧ファイル名と新ファイル名の定義
const oldPath = path.join(__dirname, 'old-name.txt');
const newPath = path.join(__dirname, 'new-name.txt');

// fs.renameを使用したファイル名変更
fs.rename(oldPath, newPath, (err) => {
  if (err) {
    // エラーが発生した場合の処理
    console.error('ファイル名の変更に失敗しました:', err);
    return;
  }
  console.log('ファイル名の変更が正常に完了しました。');
});

ファイル名の変更が正常に完了しました。

コールバック方式の注意点

コールバック方式はシンプルですが、複数の非同期処理が重なると「コールバック地獄」と呼ばれる状態に陥りやすくなります。

また、エラーハンドリングを各コールバック内で行う必要があるため、コードが冗長になりがちです。

小規模なスクリプトやレガシーなシステムでない限り、次に紹介するPromise版の使用を検討してください。

fs.promises.renameによるモダンな実装

現在のNode.js開発において、最も推奨されるのがfs.promisesモジュールを使用した実装です。

async/await構文と組み合わせることで、非同期処理を同期処理のような感覚で簡潔に記述できます。

async/awaitを活用したメリット

PromiseベースのAPIを使用すると、try...catch構文を利用した一括でのエラーハンドリングが可能になります。

これにより、エラーの捕捉漏れを防ぎ、プログラムの堅牢性を高めることができます。

また、トップレベルawaitがサポートされている環境では、モジュールの直下で非同期処理を記述することも容易です。

実装コード例

以下は、ESモジュール形式でfs.promises.renameを利用したコード例です。

import { rename } from 'node:fs/promises';
import { join } from 'node:path';

async function renameFile() {
  const oldPath = join(process.cwd(), 'old-data.csv');
  const newPath = join(process.cwd(), 'new-data.csv');

  try {
    // 非同期でファイル名を変更
    await rename(oldPath, newPath);
    console.log('Promise形式での変更に成功しました。');
  } catch (error) {
    // 実行時エラーのキャッチ
    console.error('エラーが発生しました:', error.message);
  }
}

renameFile();

Promise形式での変更に成功しました。

並列処理との相性

fs.promisesを使用すると、Promise.allなどを用いて複数のファイル名変更を並列に実行することも可能です。

大量のファイルを一括でリネームするバッチ処理などでは、この特性が大きなパフォーマンス向上に寄与します。

fs.renameSyncによる同期的なファイル名変更

特定のケースにおいては、同期メソッドであるfs.renameSyncを使用することが適切な場合があります。

同期メソッドは処理が完了するまで次の行のコードを実行しないため、メインスレッドをブロックします。

同期メソッドの主な用途

スクリプトの起動時など、ファイル名の変更が完了しないと後続の処理が進められない場合に限定して使用するのが一般的です。

例えば、設定ファイルの読み込み前にファイルをリネームする必要があるCLIツールの作成などが挙げられます。

Webサーバーなどの高トラフィックな環境では、パフォーマンス低下を招く恐れがあるため使用を避けるべきです。

実装コード例

同期方式の実装は非常にシンプルです。

const fs = require('node:fs');

try {
  // 同期的にファイル名を変更
  fs.renameSync('config.old.json', 'config.json');
  console.log('同期処理による変更が完了しました。');
} catch (err) {
  console.error('同期処理中にエラーが発生しました:', err);
}

同期処理による変更が完了しました。

実務で遭遇するエラーコードとその対策

ファイル名変更の操作は、様々な理由で失敗する可能性があります。

エラーオブジェクトに含まれるコードを確認することで、原因を正確に特定し適切な対処を行うことができます。

主なエラーコード一覧

以下に、ファイル操作時によく発生するエラーコードをまとめました。

EXDEVエラーへの特別な対応

fs.renameは同一のファイルシステム内での「リネーム（移動）」を想定したシステムコールを利用します。

そのため、異なる物理ディスクやマウントポイント間でファイルを移動させようとすると、EXDEVというエラーが発生します。

この場合は、ファイルを一旦読み込んでコピーを作成し、元のファイルを削除するという手順を踏む必要があります。

Node.jsの標準ライブラリだけで対応する場合は、fs.copyFileとfs.unlinkを組み合わせるか、streamを利用してデータを転送します。

ファイル名変更を安全に行うためのベストプラクティス

単にメソッドを呼び出すだけでなく、本番環境で安全に動作させるためにはいくつかのベストプラクティスを守る必要があります。

1. 事前にファイルの存在を確認する

変更元のファイルが存在しない場合にrenameを呼び出すと必ずエラーになります。

fs.promises.accessやfs.existsSyncを使用して、事前にファイルがあることを確認するか、エラーハンドリングを厳密に行いましょう。

ただし、確認と実行の間にファイルが消える可能性（TOCTOU問題）があるため、try…catchでのエラー補足が最も確実な方法です。

2. ディレクトリの存在を確認する

新しいファイル名として指定するパスの「親ディレクトリ」が存在しない場合もエラーとなります。

新しいパスを作成する前に、fs.mkdirをrecursive: trueオプション付きで実行し、ディレクトリ階層を確実に作成しておくことが推奨されます。

3. パスの正規化を行う

ユーザー入力や設定ファイルからパスを取得する場合、不正な文字列が含まれている可能性があります。

path.normalizeやpath.resolveを使用して、パスを安全な形式に整形してから使用するようにしましょう。

各メソッドの比較まとめ

最後に、今回紹介した各メソッドの特性を比較表としてまとめます。

まとめ

Node.jsでファイル名を変更する方法には複数のアプローチがありますが、現代の開発においてはfs.promises.renameを活用したasync/awaitによる実装がベストプラクティスです。

この方法はコードの可読性を高めるだけでなく、エラーハンドリングを統合しやすく、保守性の高いプログラムを構築するのに役立ちます。

一方で、OSのファイルシステム制限や権限によるエラー、異なるデバイス間での移動といった実務特有の課題も存在します。

これらのエラー特性を理解し、pathモジュールによる正確なパス指定と組み合わせることで、安全で堅牢なファイル操作機能を実装できるようになります。

本記事で解説した各手法の特徴とエラーへの対策を参考に、プロジェクトに最適なファイル管理処理を構築してください。