macOS iCloud Desktop Sync で開発環境が壊れる・dev server が固まる原因と対策【.nosync / metadata.nosync とは何かも解説・全言語共通】

公開日：2026-04-16／カテゴリ：macOS・開発環境・トラブルシューティング／AnchorUp 技術ブログ

「Next.js の dev server が突然固まる」「git status が秒単位で固まるようになった」「Python の venv が壊れる」「Rust の target/ が勝手に消える」——もしあなたの開発プロジェクトが ~/Desktop または ~/Documents 配下に置かれているなら、犯人はコードでもフレームワークでもなく macOS の iCloud Desktop & Documents Sync かもしれない。

これは Node.js 固有の問題ではない。言語・フレームワークを問わず、Mac で開発する全員が踏む可能性のある地雷だ。しかも日本語圏ではこの問題を正面から扱った記事がほぼ無く、「Next.js 遅い」で検索しても webpack や Docker の話ばかりヒットして本当の原因に辿り着けない。

この記事では、なぜ iCloud Desktop Sync が開発環境を壊すのか、その根本原因を4層に分解した上で、言語別の被害事例と brctl コマンドを使った診断方法、そして3段階の対策を解説する。Mac の中に metadata.nosync のような .nosync で終わるフォルダ/ファイルを見つけて「これは何？消していい？」と検索して来た人は、後半の「.nosync とは何か」のセクションに答えをまとめている。

よくある症状：言語は違っても原因は同じ

以下の症状のうち、どれか1つでも心当たりがあれば、iCloud が原因の可能性が高い。

これらは一見バラバラに見えるが、根本原因は全て同じだ。

犯人: iCloud Desktop & Documents Sync + ストレージ最適化

macOS には iCloud Desktop & Documents Sync という機能がある。システム設定の「Apple ID → iCloud → iCloud Drive → デスクトップと書類フォルダ」がこれだ。これを ON にすると、~/Desktop と ~/Documents 配下の全ファイルが iCloud Drive に同期される。

問題なのは 「Mac のストレージを最適化」が同じ画面でデフォルト ON になっている点だ。この機能は、OS が「最近アクセスされていない」と判断したファイルをローカル実体から削除し、iCloud 上にのみ残す挙動を取る。必要になった瞬間に再ダウンロードして復元する仕組みで、これを dataless 化（または evict）と呼ぶ。

この仕組み自体は、写真やドキュメントのような「たまにしか開かないファイル」には便利だ。しかし開発プロジェクトに適用されると、次の4つのメカニズムを通じて地獄の扉を開く。

根本原因の4層：言語非依存で壊れる理由

1. dataless 化によるランダムなファイル消失

OS から見て「ユーザーが Finder で開いてない」ファイルは evict 候補になる。node_modules/ の中身、venv/ の中身、target/debug/ のビルド成果物、.git/objects/ の pack ファイル——ユーザーが直接クリックしないファイルこそが最も evict されやすい。

dataless 化されたファイルは、アクセスされた瞬間に同期ダウンロードが走る。数万ファイルある node_modules が一斉に evict されると、npm run dev の起動時に数分〜十数分のフリーズが発生する。

2. fsevents / ファイル監視の破綻

Next.js や Vite、webpack、turbopack、chokidar は全て macOS の FSEventStream API（fsevents） を使ってファイル変更を監視している。

dataless ファイルに対してファイル監視を張ると、watcher が stall したり、誤発火したり、イベントを取りこぼしたりする。HMR が効かない、保存しても反映されない、ビルドが途中で止まる——こうした症状の多くはこれが原因だ。

3. symlink のサポート不備

iCloud Drive は symlink（シンボリックリンク）を完全にはサポートしていない。同期の過程で symlink が実体化されたり、壊されたり、権限が変わったりする。これが特に刺さるのは以下のケースだ。

4. 拡張属性（xattr）の剥奪

macOS は拡張属性（com.apple.quarantine, com.apple.metadata:* など）をファイルに付与している。iCloud を経由して同期されたファイルは、この xattr の一部が落ちることがある。

影響を受けるのは署名検証、コード実行許可、Gatekeeper の判定など。特にビルドツールが生成したバイナリや、ダウンロードしたアセットで問題が起きやすい。

言語・ツール別の被害事例

ここまで読んで「自分が使ってる言語は大丈夫か?」と不安になったはずだ。言語別に具体的な被害を整理する。

Node.js / Next.js / Vite

最も被害が派手で、英語圏では既に専用の CLI ツール（nosync-icloud, nocloud）まで存在する。

Error: ENOENT: no such file or directory, open '/Users/you/Desktop/app/node_modules/next/dist/compiled/...'

これは node_modules 配下のファイルが dataless 化された状態でアクセスされ、同期 DL が間に合わなかった場合に出る典型的なエラーだ。.next/ や .vite/ のビルドキャッシュも同様に evict される。

Python（venv / Poetry / uv）

$ source venv/bin/activate
$ python
zsh: ./venv/bin/python: bad interpreter: no such file or directory

venv の bin/python が Python 本体への symlink だったが、iCloud 同期で壊れたパターン。site-packages/ 内の .pyc ファイルが evict されると ModuleNotFoundError が唐突に出る。Poetry や uv も同じ問題を抱える。

Rust（Cargo）

target/ ディレクトリは 1 プロジェクトで簡単に数 GB を超える。iCloud 容量を圧迫するだけでなく、evict されると incremental build が効かず毎回フル再ビルドになる。しかも symlink を多用する target/doc や target/release が壊れる。

Go

$GOPATH/pkg/mod が ~/go にあれば直接の被害はないが、プロジェクト内に vendor/ を置いている場合は同じ被害を受ける。Go は独自の module cache を持つので、cache 内の ZIP が evict されると go mod download が失敗する。

Git（全言語共通の地雷）

これは言語に関係なく全プロジェクトが踏む。.git/objects/ 配下のオブジェクトファイル（特に .git/objects/pack/*.pack）が evict されると、次のような症状が出る。

fatal: bad object HEAD
error: object file .git/objects/ab/cdef... is empty
fatal: loose object abcdef... (stored in .git/objects/ab/cdef...) is corrupt

Git の pack ファイルは数百 MB になることもあり、dataless 化の最有力候補だ。一度 .git が壊れると修復は非常に面倒で、最悪 clone し直しになる。

Xcode / Flutter / CocoaPods

Apple 自身が Xcode プロジェクトを iCloud Drive 配下に置くことを非推奨にしている。Flutter も公式ドキュメントで同様に警告している。DerivedData, Pods/, .dart_tool/, ios/Flutter/ などが全て被害を受ける。

Docker Desktop

~/Desktop 配下のディレクトリを volume mount するとさらに悲惨だ。iCloud → macOS ファイルシステム → Docker の仮想化レイヤーという多段同期が発生し、I/O が実用にならない速度まで劣化する。

自分が踏んでいるか確認する：brctl コマンド

macOS には brctl（bird control の略、bird は iCloud 同期デーモン）という CLI ツールが標準で入っている。これで dataless 化の状態を確認できる。

# プロジェクトディレクトリが iCloud 管理下にあるか確認
brctl status ~/Desktop/my-project

# dataless 化されているファイルを一覧
brctl download ~/Desktop/my-project/node_modules  # 強制的に全部DL

# iCloud 管理下にあるディレクトリを再帰的にチェック
find ~/Desktop/my-project -type f -exec ls -lO {} \; | grep dataless

ファイルのフラグに dataless が含まれていれば、それはローカル実体が無く雲の中にしかない。ls -lO の出力で dataless フラグを持つファイルが大量に見つかったら、確実に被害を受けている。

また、Finder で ~/Desktop を開いてファイル名の横に雲マーク（↓付きクラウドアイコン）が表示されていれば、そのファイルは evict 済みだ。

対策：3段階で根治する

対策は「根本解決」「妥協解決」「応急処置」の3段階がある。おすすめは 1（根本解決） だ。

対策1（推奨）: 開発ディレクトリを iCloud の外に出す

最も確実で、二度とこの問題に悩まされない方法。~/code, ~/dev, ~/src など ~/Desktop と ~/Documents の外 に開発用ディレクトリを作り、全プロジェクトを移動する。

mkdir -p ~/code
mv ~/Desktop/my-project ~/code/my-project
cd ~/code/my-project

# node_modules は作り直すのが安全
rm -rf node_modules
npm install

~/code のようなホームディレクトリ直下のパスは iCloud Desktop & Documents Sync の管轄外なので、同期も dataless 化も発生しない。

VS Code や Cursor の「最近開いたプロジェクト」は一度クリアされるが、これは一時的な代償だ。

対策2: iCloud Desktop & Documents Sync を OFF にする

開発以外にも ~/Desktop を使っているが、同期は不要な場合。システム設定から以下の手順で OFF にできる。

  1. システム設定を開く
  2. Apple ID → iCloud → iCloud Drive
  3. 「オプション」をクリック
  4. 「デスクトップと書類フォルダ」のチェックを外す

注意点として、OFF にすると iCloud 上のファイルが 一度ローカルから消える ように見える。実際には ~/Library/Mobile Documents/ 配下に残っているので、必要なファイルは手動で ~/Desktop に戻す必要がある。事前に別の場所にバックアップを取っておくと安全だ。

対策3（応急処置）: .nosync 拡張子でフォルダを除外する

iCloud は .nosync で終わる名前のファイル/フォルダを同期対象から除外する 特殊ルールを持っている。これを利用して、node_modules だけを除外できる。

cd ~/Desktop/my-project
mv node_modules node_modules.nosync
ln -s node_modules.nosync node_modules

node_modules.nosync が実体で、node_modules はそれへの symlink。iCloud は .nosync ディレクトリを無視するため同期されない。

同じ手法で target.nosync, venv.nosync, .git.nosync なども作れる。ただし .git を symlink にすると一部の Git ツールが動かなくなる ため、Git ディレクトリに対してはこの手法は避けた方が良い。

この方法は「Desktop から離れたくない」場合の応急処置として有効だが、プロジェクトが増えるたびに手動で対応する必要があるのでスケールしない。nosync-icloud のような CLI ツールで自動化する選択肢もある。

ただし .nosync には 「親フォルダごと退避・削除されると中身も一緒に消える」という致命的な落とし穴がある。応急処置として使う前に、次のセクションの注意点を必ず読んでほしい。

.nosync とは何か？「metadata.nosync」フォルダの正体と、削除していいのか

結論: .nosync は「このファイル/フォルダは iCloud に転送しない」という Apple が定めた名前のルールだ。Mac の中で metadata.nosync のような名前のフォルダやファイルを見つけたなら、それは アプリが「この Mac だけで持てばよいデータ（キャッシュやインデックス等のメタデータ）」を、iCloud の容量と同期時間を無駄にしないために意図的に作ったものであり、壊れているわけでもウイルスでもない。放置して問題ないし、自分で作ったものでない限り手動で消す必要もない。

.nosync は Apple 公式の仕様なのか

公式の仕様だ。ただし一般ユーザー向けのサポート文書ではなく、**アプリ開発者向けの「iCloud Design Guide」**に書かれている。原文を引用する。

One way to prevent files and directories from being stored in iCloud is to add the .nosync extension to the file or directory name. When iCloud encounters files and directories with that extension in the local container directory, it does not transfer them to the server. You might use this extension on temporary files that you want to store inside a file package, but that you do not want transferred with the rest of that package’s contents.

（訳）ファイルやディレクトリを iCloud に保存させない方法のひとつは、ファイル名またはディレクトリ名に .nosync 拡張子を付けることだ。iCloud はローカルコンテナ内でこの拡張子を持つファイル/ディレクトリに出会うと、それをサーバに転送しない。ファイルパッケージの中に置きたいが、パッケージの他の内容と一緒に転送はしたくない一時ファイルなどに使うとよい。

— Apple Developer Documentation Archive「iCloud Design Guide › iCloud Fundamentals」

ポイントは3つある。

疑問 答え
ファイルだけ？フォルダにも効く？ 両方に効く。原文が “file or directory name” と明記している。フォーラムには「フォルダには効かず .tmp だけが有効」という古い情報もあるが、node_modules.nosync が世界中で使われている通りフォルダでも機能する
なぜアプリが metadata.nosync を作るのか 原文の通り、「同期したくない一時データやメタデータ」をアプリのコンテナ内に置くための想定用途そのもの。検索インデックス・サムネイルキャッシュ・端末固有の設定などが典型
削除していいか アプリが作ったものなら消さなくてよい。消してもアプリが再生成するのが普通だが、再インデックス等で一時的に重くなることがある。消すならそのアプリを終了してから。自分で作った node_modules.nosync 等は当然消してよい

誰が metadata.nosync を作ったのかを特定する方法

.nosync のファイル/フォルダは、それを作ったアプリの iCloud コンテナの中にあるのが普通だ。コンテナのディレクトリ名にアプリの Bundle ID が入っているので、パスを見れば犯人が分かる。

# iCloud コンテナ配下の .nosync を一覧（-maxdepth を増やすと深い階層も探せる）
find ~/Library/Mobile\ Documents -maxdepth 4 -name "*.nosync" 2>/dev/null

# 出力例
# /Users/you/Library/Mobile Documents/iCloud~com~example~notesapp/Documents/metadata.nosync
#                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ← このアプリが作った

iCloud~com~example~notesapp の部分が Bundle ID（. が ~ に置き換わっている）で、com.example.notesapp というアプリのコンテナだと分かる。~/Desktop や ~/Documents 直下に見つかった場合は、iCloud Desktop & Documents Sync によってそれらのフォルダ自体が iCloud コンテナ扱いになっているため、そこにデータを置くアプリ（ノート・PDF・ライブラリ管理系が多い）が作ったものだ。

.nosync の3つの落とし穴：中身が消える・エラーコード-43・非公式扱い

落とし穴1: 親フォルダを退避・削除すると .nosync の中身も一緒に消える（最重要）

同じ公式ドキュメントに、次の一文が続いている。

Although items with the .nosync extension are not transferred to the server, they are still bound to their parent directory. When you delete the parent directory in iCloud, or when you evict the parent directory and its contents locally, the entire contents of that directory are deleted, including any .nosync items.

（訳）.nosync の項目はサーバに転送されないが、親ディレクトリには紐付いたままだ。iCloud 上で親ディレクトリを削除したとき、または親ディレクトリとその中身をローカルから退避（evict）したとき、その中身は .nosync の項目も含めて全て削除される。

つまり .nosync は「iCloud に上がらない」だけで、「iCloud の管理から外れる」わけではない。iCloud 側には存在しないので、消えたら iCloud.com からも復元できない。Apple サポートコミュニティには、iCloud Drive の同期不良を直そうと「デスクトップと書類フォルダ」を一度 OFF → ON にしたところ、~/Documents 内の .nosync フォルダだけが「iCloud Drive Archive」にも入らずに消え、半年分の作業を失ったという報告がある。この記事の対策2（Sync を OFF にする）を実行する前に、.nosync フォルダを iCloud 管轄外（~/code など）へ退避しておくこと。Time Machine を有効にしておくのは大前提だ。

落とし穴2: macOS Sonoma 14 では .nosync 内の移動・削除で「エラーコード-43」が出る

macOS Sonoma 14.0〜14.x では、.nosync フォルダ内のファイルをゴミ箱に入れたり移動しようとすると、Finder が次のエラーを出す事象が知られている。

いくつかの必要な項目が見つからなかったため、操作を完了できません。（エラーコード-43）

回避策は、ゴミ箱を経由せず Finder の「すぐに削除…」（Option + Command + Delete）で直接消すこと。macOS Sequoia 15 以降では解消している。

落とし穴3: 一般向けには「非公式」の扱いで、将来変わる可能性がある

前述の通り .nosync は開発者向けドキュメントにしか書かれておらず、Apple のユーザー向けサポートページには載っていない。挙動が OS のアップデートで変わっても告知されない可能性がある。だからこそ、開発ディレクトリを守る手段としては .nosync はあくまで応急処置で、対策1（iCloud の外に出す）が根本解決になる。

.nosync が効いているか確認する方法

Finder で対象のフォルダを見て、名前の横に iCloud の状態アイコン（雲マーク・チェックマーク・進行中の円）が表示されていなければ除外できている。brctl で同期ログを流しながら、そのフォルダ内で touch してもアップロードが走らないことでも確認できる。

# 別ターミナルで iCloud 同期ログを流す
brctl log --wait --shorten

# 対象フォルダ内でファイルを作り、ログに転送が現れないことを確認
touch ~/Desktop/my-project/node_modules.nosync/probe.txt

「私は ~/Desktop で開発してる、おかしい?」への回答

全くおかしくない。以下の理由から、非常に多くの macOS 開発者がこの罠に無自覚に落ちている。

  1. iCloud Desktop & Documents Sync は macOS のセットアップ時にデフォルト ON を推奨される。多くのユーザーは何も考えずに ON のまま使っている
  2. ~/Desktop と ~/Documents は最も直感的な作業場所であり、ここにプロジェクトを置くのはごく自然
  3. 症状が出るまで iCloud が原因だと気付けない。dev server が遅ければ webpack を疑い、git が壊れれば自分の操作ミスを疑う。まさか OS の同期機能が犯人とは思わない
  4. 英語圏では有名な問題だが、日本語の情報が極端に少ない。「Next.js 遅い」で検索しても Docker や webpack の話ばかり出てくる

Apple Developer Forums にもこの問題の専用スレッドがあり、プロの iOS/macOS エンジニアでも踏んでいる。恥じる必要は全くないが、気付いた今日が対策のタイミングだ。

まとめ：開発環境を守る iCloud 対策チェックリスト

□ プロジェクトが ~/Desktop または ~/Documents 配下にないか確認する
  → 配下にあれば iCloud Desktop & Documents Sync の管轄範囲

□ システム設定で「Mac のストレージを最適化」がデフォルト ON になっている
  → dataless 化（evict）が自動発生している可能性が高い

□ brctl status <path> で iCloud 管理下か確認する
  → ls -lO で dataless フラグを持つファイルが大量にあれば被害確定

□ 開発ディレクトリを ~/code や ~/dev など iCloud 管轄外に移動する（推奨）
  → 同期も dataless 化も発生しない、根本解決

□ Desktop を使い続けたい場合は Desktop & Documents Sync を OFF にする
  → 事前にバックアップを取ってから切り替える

□ 応急処置として node_modules.nosync + symlink で除外する
  → プロジェクトが多い場合はスケールしないので注意

□ .git ディレクトリは nosync 化しない
  → Git ツールの一部が symlink 化された .git に対応していない

□ .nosync の中身は iCloud に無いので、親フォルダの退避・削除や Sync の OFF→ON で消える
  → Sync を切り替える前に .nosync フォルダを ~/code などへ退避、Time Machine は必須

□ metadata.nosync など自分が作っていない .nosync はアプリのローカル専用データ
  → 壊れていない。放置してよく、消すならそのアプリを終了してから

Node.js、Python、Rust、Go、Xcode——どの言語で開発していても、~/Desktop や ~/Documents 配下にプロジェクトを置いている限り、この問題は等しく襲ってくる。フレームワークのアップデートで直る類の問題ではないので、開発ディレクトリを iCloud の外に出すのが最も確実な予防策だ。

もし今、原因不明の dev server フリーズや git 破損に悩まされているなら、まず brctl status でプロジェクトの状態を確認してみてほしい。案外、あなたのコードは最初から壊れていなかったのかもしれない。

技術ブログの記事一覧へ