edgeone-pages-dev

EdgeOne Pages 開発ガイド

EdgeOne Pages 上でフルスタックアプリケーションを開発します。Edge Functions、Cloud Functions（Node.js／Go／Python）、Middleware を利用できます。

このスキルを使用する場面

• EdgeOne Pages で API、サーバーレス関数、バックエンドロジックを作成する場合
• リクエストのインターセプト、リダイレクト、認証ガード、A/B テストのためのミドルウェアを追加する場合
• 静的フロントエンドとサーバーサイド関数を組み合わせてフルスタックアプリを構築する場合
• エッジ側の永続データに KV Storage を使用する場合
• WebSocket エンドポイントを設定する場合（Node.js ランタイム）
• EdgeOne Pages 上で Express、Koa、Gin、Echo、Flask、FastAPI、Django を統合する場合
• EdgeOne Pages のランタイムエラー（関数の失敗、ミドルウェアの問題、KV の問題）をデバッグする場合

次の場合は使用しないでください：

• デプロイ → edgeone-pages-deploy スキルを使用してください
• Next.js／Nuxt のミドルウェアや API ルート → プラットフォームの middleware.js ではなく、フレームワーク独自の API を使用してください
• EdgeOne Pages プロジェクト以外での一般的な Express／Koa／Gin／Flask の開発
• Cloudflare Workers、Vercel Functions、その他のプラットフォーム

このスキルの使用方法（コーディングエージェント向け）

1. 以下の決定ツリーを読んで、適切なランタイムを選択します
2. ルーティングの表に従って、関連するリファレンスファイルを読み込みます
3. リファレンスのコードパターンを使って、ユーザーの要求を実装します

⛔ 重要なルール（必ず守ってください）

1. タスクに適したランタイムを選択してください。 決定ツリーに従い、推測で選ばないでください。
2. Edge Functions は Node.js ではなく V8 上で実行されます。 Edge Functions では Node.js の組み込みモジュール（Node.js の fs、path、crypto）や npm パッケージを使用しないでください。
3. Cloud Functions は Node.js、Go、Python の 3 つのランタイムに対応しています。 すべての関数ファイルを cloud-functions/ ディレクトリに配置してください。プラットフォームはファイル拡張子で言語を検出します（.js／.ts → Node.js、.go → Go、.py → Python）。
4. Node.js 関数は標準の Web Response オブジェクトを返します。 [[default]].js パターンで Express／Koa を使用する場合を除き、res.send() は使用しないでください。
5. Go のハンドラーモードでは http.HandlerFunc シグネチャが必要です。フレームワークモードでは、標準的なフレームワークコードを使用し、ポートとパスは自動的に適合されます。
6. Python のエントリーファイルはクラス／アプリのパターン（class handler(BaseHTTPRequestHandler)、app = Flask(...)、app = FastAPI(...)）によって識別されます。それ以外の .py ファイルはヘルパーモジュールとして扱われます。
7. Middleware は軽量なリクエストのインターセプト専用です。 Middleware に重い計算やデータベース呼び出しを含めないでください。
8. ローカル開発には必ず edgeone pages dev を使用してください。 関数用の開発サーバーを別途起動しないでください。CLI がポート 8088 ですべてを処理します。
9. edgeone pages dev を edgeone.json の devCommand または package.json の dev スクリプトとして設定しないでください。 無限再帰が発生します。
10. フレームワークプロジェクト（Next.js、Nuxt など）では、プラットフォームの middleware.js ではなく、フレームワーク独自のミドルウェアを使用してください。

---

技術選択ツリー

Request interception / redirect / rewrite / auth guard / A/B test?
  → Middleware                                        → read references/middleware.md

Lightweight API with ultra-low latency (simple logic, no npm)?
  → Edge Functions                                    → read references/edge-functions.md

KV persistent storage? (⚠️ enable KV in console first)
  → Edge Functions + KV Storage                       → read references/kv-storage.md

Complex backend with npm packages / database / WebSocket?
  → Cloud Functions (Node.js)                         → read references/node-functions.md

Express or Koa framework?
  → Cloud Functions (Node.js) with [[default]].js     → read references/node-functions.md

High-performance API with Go (Gin / Echo / Chi / Fiber)?
  → Cloud Functions (Go)                              → read references/go-functions.md

Python API with Flask / FastAPI / Django / Sanic?
  → Cloud Functions (Python)                          → read references/python-functions.md

Pure static site with no server-side logic?
  → No functions needed — just deploy static files

Need a project structure template?
  → read references/recipes.md

ランタイムの比較

機能	Edge Functions	Cloud Functions（Node.js）	Cloud Functions（Go）	Cloud Functions（Python）	Middleware
ランタイム	V8（CF Workers と同様）	Node.js v20.x	Go 1.26+	Python 3.10	V8（エッジ）
npm／パッケージ	❌ 非対応	✅ npm エコシステム全体に対応	✅ Go モジュール	✅ pip（自動検出）	❌ 非対応
コードサイズの上限	5 MB	128 MB	128 MB	128 MB（依存関係を含む）	エッジバンドルの一部
リクエストボディの上限	1 MB	6 MB	6 MB	6 MB	該当なし（そのまま転送）
CPU時間／実行時間の上限	CPU 200 ms	実時間 120 s	実時間 120 s	実時間 120 s	軽量処理のみ
KV Storage	✅ あり（グローバル変数）	❌ なし	❌ なし	❌ なし	❌ なし
WebSocket	❌ なし	✅ あり	❌ なし	❌ なし	❌ なし
フレームワークのサポート	—	Express、Koa	Gin、Echo、Chi、Fiber	Flask、FastAPI、Django、Sanic	—
ユースケース	軽量 API、エッジコンピューティング	複雑な API、フルスタック	高性能 API、コンパイルによる高速化	データサイエンス、ML、迅速なプロトタイピング	リクエストの前処理

Cloud Functions — 言語の比較

機能	Node.js	Go	Python
ファイル拡張子	.js / .ts	.go	.py
ハンドラースタイル	export function onRequest(ctx) → Response	func Handler(w, r)（Handler）または func main()（フレームワーク）	class handler(BaseHTTPRequestHandler) またはフレームワークのアプリケーションインスタンス
フレームワークモード	[[default]].js による Express／Koa	エントリー .go ファイルによる Gin／Echo／Chi／Fiber	エントリー .py ファイルによる Flask／FastAPI／Django
依存関係の管理	package.json（npm）	go.mod（自動）	requirements.txt ＋自動検出
開発モード	Handler ／ Framework	Handler ／ Framework	Handler ／ WSGI ／ ASGI

---

ルーティング

タスク	参照先
Edge Functions（軽量 API、V8 ランタイム、KV Storage）	references/edge-functions.md
KV Storage（エッジでの永続的なキーと値のストレージ）	references/kv-storage.md
Cloud Functions — Node.js（npm、データベース、Express／Koa、WebSocket）	references/node-functions.md
Cloud Functions — Go（Gin、Echo、Chi、Fiber、net/http）	references/go-functions.md
Cloud Functions — Python（Flask、FastAPI、Django、Sanic、Handler）	references/python-functions.md
Middleware（リダイレクト、リライト、認証ガード、A/B テスト）	references/middleware.md
プロジェクト構成テンプレートと一般的なレシピ	references/recipes.md
デバッグとトラブルシューティング	references/troubleshooting.md

---

プロジェクトのセットアップ（クイックスタート）

プロジェクトを初期化します：

edgeone pages init

ローカル開発を開始します：

edgeone pages dev            # Serves everything on http://localhost:8088/

プロジェクトをリンクします（KV と環境変数に必要です）：

edgeone pages link

環境変数を管理します：

edgeone pages env pull       # Pull from console to local .env

関数内では context.env.KEY（Node.js）、os.Getenv("KEY")（Go）、または os.environ.get("KEY")（Python）を使って環境変数にアクセスできます。

プロジェクト構成とレシピの詳細については、references/recipes.md を参照してください。