Gadget 01：macOS セットアップ

Cloudflare OS を macOS で動かすための前提条件・権限・セットアップの罠を整理

macOS セットアップ

macOS で Cloudflare OS（run-local）を動かすときの前提条件、必要な権限、 そして最初にハマりがちな罠を詰め込みます。

目的

  • macOS 上の実行環境を正しく準備し、pnpm run-local を一度で成功させる
  • 後から痛い目を見ないための権限・ディスク・ネットワークの注意点を把握する

前提条件

項目 必要条件 備考
OS macOS 13+ 推奨 Rosetta 不要（x86_64 / Apple Silicon どちらも可）
Node.js 20.19+ / 22.12+ 22 LTS 推奨。nvm / asdf / fnm どれでも
pnpm 11.x corepack prepare pnpm@11.17.0 --activate
git 2.x clone / 更新管理用
ディスク空き 5 GB 以上 モノレポ + node_modules 
# 一括確認
node --version && pnpm --version && git --version

手順

  1. Node.js 22 LTS を入れる（例: fnm）
fnm install 22 && fnm use 22 && fnm default 22
  1. corepack で pnpm を揃える
corepack enable
corepack prepare pnpm@11.17.0 --activate
  1. リポジトリを取得して起動
git clone https://github.com/cloudflare/cloudflare-os.git
cd cloudflare-os
pnpm install
pnpm run-local
Tip初回起動は時間がかかる

run-local 初回はフロントビルド＋依存解決で数分かかります。 node_modules が大きいので、初回の pnpm install は余裕を持って待ちましょう。

よくある失敗

1. gyp 系（ネイティブビルド）で失敗

  • 原因: Xcode Command Line Tools が未導入

  • 対処:

    xcode-select --install

2. EADDRINUSE 0.0.0.0:8787

  • 原因: 前に起動したプロセスが残っている

  • 対処:

    lsof -i :8787
kill <PID>

3. ディスク不足で pnpm install が止まる

  • 原因: /Users/<you> の空きが少ない
  • 対処: df -h で確認。不要な node_modules やキャッシュを掃除（pnpm store prune）

4. node のバージョンが頻繁に変わる

  • 原因: .nvmrc / .node-version と実環境の乖離
  • 対処: リポジトリの packageManager / .nvmrc 記載に合わせ、毎回明示的にセット

確認

次に読む