日本人エンジニアなら必ず一度は時間を溶かすNFD問題 ~Viteのビルドが謎のエラーで落ちる現象と解決策~

はじめに

Rails 8 + Vite + React のモダンなハイブリッド構成で開発を進めていた際、ローカルの開発サーバー（bin/vite dev）では正常に画面が表示されるのに、ビルド（bin/vite build）を実行した途端に謎のエラーで落ちるという現象に遭遇しました。

設定ファイルやディレクトリ構成をいくら見直しても原因が分からず数時間を溶かしましたが、原因は非常に意外な「Mac特有の文字コード問題（NFD問題）」でした。

同じエラーで絶望している方の助けになればと思い、備忘録として残します。

遭遇したエラー

bin/vite build --clear --mode=development を実行した際、以下のようなエラーが発生しました。

error during build:
Build failed with 1 error:

[INVALID_OPTION] Error: You must supply `options.input` to rolldown, you should at least provide one entrypoint via `options.input` or `this.emitFile({type: 'chunk', ...})` (https://rollupjs.org/plugin-development/#this-emitfile)

このエラー文自体は、「ビルドの起点となるファイル（エントリーポイント）が1つも見つからない」ということを示しています。

通常であれば、以下のポイントを疑うのが定石です。

• app/frontend/entrypoints/ ディレクトリ内にファイルが存在しない
• config/vite.json の sourceCodeDir の設定ミス
• vite.config.js で RubyPlugin() が読み込まれていない

しかし、これらは全て完璧に設定されており、何一つ間違っていませんでした。

真の原因：「ポートフォリオ」というフォルダ名

エラーログのパスをよく見ると、以下のような文字列が混じっていました。
file:///Users/.../Desktop/%E3%83%9B%E3%82%9A.../Yukidama/

これをデコードすると、「ポートフォリオ」 になります。
そう、プロジェクトの親フォルダ名に、濁点・半濁点を含む日本語を使用していたことが全ての元凶でした。

NFD問題（Macの文字コードの罠）とは？

Macのファイルシステム（APFSなど）と、Node.js（Vite）の間で、濁点・半濁点の扱い方に致命的な違いがあることで発生する問題です。

世界中の文字を扱うUnicodeには、濁点などの表現方法に主に2つのルールがあります。

1. NFC (結合文字列):
   • 「ポ」を 1つの独立した文字 として扱う。
   • Windows、Linux、Webブラウザ、そして Node.js（Vite含む大半のプログラミング環境） が採用。
2. NFD (分解文字列):
   • 「ポ」を 「ホ」＋「゜（半濁点）」の2文字 の組み合わせとして扱う。
   • Macのファイルシステム が採用。

エラー発生のメカニズム

1. Vite（内部で使われている fast-glob という検索ライブラリ）は、NFCの「ポ」 を前提にファイルツリーを検索しようとします。
2. しかし、Mac上の実際のフォルダ名は NFDの「ホ＋゜」 として保存されています。
3. プログラム側はバイト列が一致しないため「そんなフォルダは存在しない」と判定します。
4. 結果として、ディレクトリの中身を読み込めず、「エントリーポイントが0件（空っぽ）です！」という options.input エラーを引き起こしていました。

開発画面（dev）ではブラウザから直接URLでファイルを指定するため問題が顕在化しませんが、ビルド（build）ではフォルダ全体をスキャンするため、このバグを綺麗に踏み抜くことになります。

解決策

解決策は非常にシンプルです。プロジェクトが置かれている親フォルダの名前を、半角英数字（例：portfolio）に変更するだけです。

フォルダ名を変更した後、Viteのキャッシュをクリアして再ビルドを行います。

# 古いキャッシュをクリア
bin/vite clobber

# 再ビルド
bin/vite build --mode=development

これで、嘘のように緑色の ✓ built が表示され、ビルドが通るようになります。

おわりに

「プロジェクトのパスには絶対に日本語を含めない」という開発の基本ルールですが、単に「エラーが起きやすそうだから」ではなく、「NFCとNFDの仕様の違いにより、プログラムがファイルを認識できなくなるから」という明確な技術的理由があることを身をもって学びました。

特にMacを使っていて、ViteやWebpackなどで不可解なパスエラーが出た際は、一度pwdコマンドなどで「パスに濁点・半濁点入りの日本語が含まれていないか」を疑ってみてください。