edgeone-pages-dev

EdgeOne Pages 开发指南

在 EdgeOne Pages 上开发全栈应用 — 包括边缘函数、云函数（Node.js / Go / Python）和中间件。

何时使用此技能

• 在 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 路由 → 使用框架自身的 API，而非平台的 middleware.js
• 在 EdgeOne Pages 项目之外进行通用的 Express/Koa/Gin/Flask 开发
• Cloudflare Workers、Vercel Functions 或其他平台

如何使用此技能（针对编码 Agent）

1. 阅读下方的决策树，选择正确的运行时
2. 按照路由表加载相关参考文件
3. 使用参考文件中的代码模式实现用户的请求

⛔ 重要规则（切勿跳过）

1. 为任务选择正确的运行时。 遵循决策树，切勿猜测。
2. 边缘函数运行于 V8，而非 Node.js。 切勿在边缘函数中使用 Node.js 内置模块（Node 的 fs、path、crypto）或 npm 包。
3. 云函数支持三种运行时：Node.js、Go 和 Python。 将所有函数文件放在 cloud-functions/ 目录下。平台会根据文件扩展名检测语言（.js/.ts → Node.js，.go → Go，.py → Python）。
4. Node.js 函数返回标准 Web Response 对象，而非 res.send() — 除非通过 [[default]].js 模式使用 Express/Koa。
5. Go Handler 模式要求使用 http.HandlerFunc 签名；框架模式使用标准框架代码，并自动适配端口和路径。
6. Python 入口文件通过类/应用模式识别（class handler(BaseHTTPRequestHandler)、app = Flask(...)、app = FastAPI(...)）。其他 .py 文件会被视为辅助模块。
7. 中间件仅用于轻量级请求拦截。 切勿在中间件中执行繁重计算或数据库调用。
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 / 墙钟时间上限	200 ms CPU	120 s 墙钟时间	120 s 墙钟时间	120 s 墙钟时间	仅限轻量处理
KV 存储	✅ 支持（全局变量）	❌ 不支持	❌ 不支持	❌ 不支持	❌ 不支持
WebSocket	❌ 不支持	✅ 支持	❌ 不支持	❌ 不支持	❌ 不支持
框架支持	—	Express、Koa	Gin、Echo、Chi、Fiber	Flask、FastAPI、Django、Sanic	—
适用场景	轻量级 API、边缘计算	复杂 API、全栈应用	高性能 API、编译执行速度	数据科学、机器学习、快速原型开发	请求预处理

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 存储）	references/edge-functions.md
KV 存储（边缘端的持久键值存储）	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。