From 72c6b8fcf859ba54eb966fb7dd63c946333f195a Mon Sep 17 00:00:00 2001
From: ruan-cat <77109541+ruan-cat@users.noreply.github.com>
Date: Sat, 28 Feb 2026 22:28:48 +0800
Subject: [PATCH] docs(cloudflare): fix env bindings access pattern for Nitro
 v3

Update cloudflare.md to show the correct v3 pattern (event.req.runtime.cloudflare.env)
and add a breaking change warning. Add migration section to 99.migration.md.
---
 docs/1.docs/99.migration.md              | 21 ++++++++++++++++++++-
 docs/2.deploy/20.providers/cloudflare.md | 11 ++++++++---
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/docs/1.docs/99.migration.md b/docs/1.docs/99.migration.md
index a82d2ac190..7e6fceb90d 100644
--- a/docs/1.docs/99.migration.md
+++ b/docs/1.docs/99.migration.md
@@ -58,7 +58,7 @@ Please upgrade to the [latest LTS](https://nodejs.org/en/download) version (>= 2
 
 - Check your local Node.js version using `node --version` and update if necessary.
 - If you use a CI/CD system for deployment, ensure that your pipeline is running Node.js 20 or higher.
-- If your hosting provider manages the Node.js runtime, make sure it’s set to version 20, 22, or later.
+- If your hosting provider manages the Node.js runtime, make sure it's set to version 20, 22, or later.
 
 ## Type Imports
 
@@ -103,6 +103,25 @@ Some (legacy) presets have been removed or renamed.
 | `service_worker`             | Removed due to instability |
 | `firebase`                   | Use new firebase app hosting |
 
+## Cloudflare Bindings Access
+
+In Nitro v2, Cloudflare environment variables and bindings were accessible via `event.context.cloudflare.env`.
+
+In Nitro v3, the Cloudflare preset uses [srvx](https://srvx.unjs.io/) as the underlying server layer. The Cloudflare runtime context is now attached to the request's runtime object instead of the event context.
+
+**Migration:**
+
+```diff
+-- const { cloudflare } = event.context
+-- const binding = cloudflare.env.MY_BINDING
+++ const { env } = event.req.runtime.cloudflare
+++ const binding = env.MY_BINDING
+```
+
+::warning
+The old `event.context.cloudflare.env` path may still appear to work in local development (via the Wrangler dev proxy plugin), but it will be `undefined` in production Cloudflare Workers deployments.
+::
+
 ## Changed nitro subpath imports
 
 Nitro v2 introduced multiple subpath exports, some of which have been removed or updated:
diff --git a/docs/2.deploy/20.providers/cloudflare.md b/docs/2.deploy/20.providers/cloudflare.md
index a5dc8413a2..f4644c46f8 100644
--- a/docs/2.deploy/20.providers/cloudflare.md
+++ b/docs/2.deploy/20.providers/cloudflare.md
@@ -290,14 +290,19 @@ For more details on Bindings and how to use them please refer to the Cloudflare
 
 :read-more{title="KV Storage" to="/docs/storage"}
 
-In runtime, you can access bindings from the request event, by accessing its `context.cloudflare.env` field, this is for example how you can access a D1 bindings:
+In runtime, you can access bindings from the request event via `event.req.runtime.cloudflare.env`. This is for example how you can access a D1 binding:
+
+::warning
+**Nitro v3 Breaking Change:** The `event.context.cloudflare.env` pattern from Nitro v2 no longer works in production. Use `event.req.runtime.cloudflare.env` instead. The old pattern may still appear to work in local dev (via the Wrangler proxy plugin) but will be `undefined` in production deployments.
+::
 
 ```ts
 import { defineHandler } from "nitro/h3";
 
 defineHandler(async (event) => {
-  const { cloudflare } = event.context
-  const stmt = await cloudflare.env.MY_D1.prepare('SELECT id FROM table')
+  // Nitro v3: access Cloudflare bindings via event.req.runtime.cloudflare.env
+  const { env } = event.req.runtime.cloudflare
+  const stmt = await env.MY_D1.prepare('SELECT id FROM table')
   const { results } = await stmt.all()
 })
 ```