Hono × Cloudflare Workers完全ガイド — エッジで動く高速APIをサーバーレスで構築する方法【2026年版】

# プロジェクト作成（cloudflare-workersテンプレートを選択）
npm create hono@latest my-edge-api
# テンプレート選択: cloudflare-workers

cd my-edge-api
npm install

# Wrangler CLIのグローバルインストール（未導入の場合）
npm install -g wrangler

# Cloudflareアカウントへのログイン
wrangler login

# ローカル開発サーバー起動
npm run dev
# => http://localhost:8787

# wrangler.toml
name = "my-edge-api"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# KV Namespaceのバインディング
[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-namespace-id"

# D1 Databaseのバインディング
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-d1-database-id"

# R2 Bucketのバインディング
[[r2_buckets]]
binding = "STORAGE"
bucket_name = "my-bucket"

# Workers AIのバインディング
[ai]
binding = "AI"

# 環境変数
[vars]
ENVIRONMENT = "production"

// src/index.ts
import { Hono } from 'hono'

// Bindingsの型定義
type Bindings = {
  DB: D1Database
  CACHE: KVNamespace
  STORAGE: R2Bucket
  AI: Ai
  ENVIRONMENT: string
}

// 型付きHonoインスタンス
const app = new Hono<{ Bindings: Bindings }>()

app.get('/', (c) => {
  // c.env.DBなどに型補完が効く
  const env = c.env.ENVIRONMENT
  return c.json({ env, message: 'Hello from the edge!' })
})

export default app

// D1 CRUD操作の実装例
app.get('/api/users', async (c) => {
  const result = await c.env.DB
    .prepare('SELECT * FROM users LIMIT 100')
    .all()
  return c.json(result.results)
})

app.get('/api/users/:id', async (c) => {
  const id = c.req.param('id')
  const user = await c.env.DB
    .prepare('SELECT * FROM users WHERE id = ?')
    .bind(id)
    .first()
  if (!user) return c.json({ error: 'Not found' }, 404)
  return c.json(user)
})

app.post('/api/users', async (c) => {
  const { name, email } = await c.req.json()
  const result = await c.env.DB
    .prepare('INSERT INTO users (name, email) VALUES (?, ?)')
    .bind(name, email)
    .run()
  return c.json({ id: result.meta.last_row_id }, 201)
})

app.delete('/api/users/:id', async (c) => {
  const id = c.req.param('id')
  await c.env.DB
    .prepare('DELETE FROM users WHERE id = ?')
    .bind(id)
    .run()
  return c.json({ deleted: true })
})

// KVを使ったキャッシュ実装
app.get('/api/products/:id', async (c) => {
  const id = c.req.param('id')
  const cacheKey = `product:${id}`

  // キャッシュから取得
  const cached = await c.env.CACHE.get(cacheKey, 'json')
  if (cached) {
    c.header('X-Cache', 'HIT')
    return c.json(cached)
  }

  // DBから取得してキャッシュに保存
  const product = await c.env.DB
    .prepare('SELECT * FROM products WHERE id = ?')
    .bind(id)
    .first()

  if (!product) return c.json({ error: 'Not found' }, 404)

  // TTL 3600秒でキャッシュ
  await c.env.CACHE.put(cacheKey, JSON.stringify(product), {
    expirationTtl: 3600
  })

  c.header('X-Cache', 'MISS')
  return c.json(product)
})

// R2ファイルアップロード
app.put('/api/files/:filename', async (c) => {
  const filename = c.req.param('filename')
  const body = await c.req.arrayBuffer()
  const contentType = c.req.header('content-type') ?? 'application/octet-stream'

  await c.env.STORAGE.put(filename, body, {
    httpMetadata: { contentType }
  })

  return c.json({ uploaded: filename })
})

// R2ファイルダウンロード
app.get('/api/files/:filename', async (c) => {
  const filename = c.req.param('filename')
  const object = await c.env.STORAGE.get(filename)

  if (!object) return c.json({ error: 'Not found' }, 404)

  const headers = new Headers()
  object.writeHttpMetadata(headers)
  headers.set('etag', object.httpEtag)

  return c.body(object.body, { headers })
})

// LLMテキスト生成
app.post('/api/ai/chat', async (c) => {
  const { message } = await c.req.json()

  const response = await c.env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
    messages: [{ role: 'user', content: message }]
  })

  return c.json({ reply: response.response })
})

// テキスト埋め込み（RAGなど）
app.post('/api/ai/embed', async (c) => {
  const { text } = await c.req.json()

  const embeddings = await c.env.AI.run('@cf/baai/bge-small-en-v1.5', {
    text: [text]
  })

  return c.json({ vector: embeddings.data[0] })
})

// src/index.ts
import { Hono } from 'hono'

type Bindings = { DB: D1Database }

const app = new Hono<{ Bindings: Bindings }>()

// 通常のHTTPハンドラ
app.get('/', (c) => c.text('API is running'))

// Cron Triggerハンドラ（scheduled export）
export default {
  fetch: app.fetch,
  async scheduled(event: ScheduledEvent, env: Bindings) {
    console.log('Cron triggered:', event.cron)
    // 毎日0時に古いデータを削除
    if (event.cron === '0 0 * * *') {
      await env.DB
        .prepare('DELETE FROM logs WHERE created_at < datetime("now", "-30 days")')
        .run()
    }
  }
}

[[triggers.crons]]
crons = ["0 0 * * *"]

# 本番デプロイ
npx wrangler deploy

# 特定環境へのデプロイ
npx wrangler deploy --env production

# 独自ドメインの設定（wrangler.tomlに追記）
# [[routes]]
# pattern = "api.example.com/*"
# zone_name = "example.com"

# デプロイ後の確認
npx wrangler tail  # リアルタイムログ確認

# ローカルモード（ローカルのD1・KVシミュレーター使用）
npx wrangler dev

# リモートモード（本番のD1・KVに接続して開発）
npx wrangler dev --remote

# ポートを指定
npx wrangler dev --port 9000

# マイグレーションファイルの作成
npx wrangler d1 migrations create my-database create-users

# ローカルD1への適用
npx wrangler d1 migrations apply my-database --local

# 本番D1への適用
npx wrangler d1 migrations apply my-database

# シークレットの設定（プロンプトで値を入力）
npx wrangler secret put JWT_SECRET
npx wrangler secret put DATABASE_URL

# シークレット一覧の確認
npx wrangler secret list

# シークレットの削除
npx wrangler secret delete JWT_SECRET

type Bindings = {
  DB: D1Database
  JWT_SECRET: string  // wrangler secret putで設定した値
}

# リアルタイムログストリーム
npx wrangler tail

# フィルタリング（エラーのみ）
npx wrangler tail --status error

# JSON形式で出力
npx wrangler tail --format json

import { Hono } from 'hono'
import { cors } from 'hono/cors'
import { logger } from 'hono/logger'
import { HTTPException } from 'hono/http-exception'

const app = new Hono<{ Bindings: Bindings }>()

// セキュリティヘッダーとCORS
app.use('*', cors({ origin: ['https://yourdomain.com'] }))
app.use('*', logger())

// グローバルエラーハンドリング
app.onError((err, c) => {
  if (err instanceof HTTPException) {
    return c.json({ error: err.message }, err.status)
  }
  console.error('Unhandled error:', err)
  return c.json({ error: 'Internal Server Error' }, 500)
})

// 404ハンドリング
app.notFound((c) => c.json({ error: 'Not Found' }, 404))

// シンプルなレート制限（KVベース）
app.use('/api/*', async (c, next) => {
  const ip = c.req.header('CF-Connecting-IP') ?? 'unknown'
  const key = `ratelimit:${ip}`
  const count = parseInt(await c.env.CACHE.get(key) ?? '0')

  if (count > 100) {
    throw new HTTPException(429, { message: 'Too Many Requests' })
  }

  await c.env.CACHE.put(key, String(count + 1), { expirationTtl: 60 })
  await next()
})

export default app