edgeone-pages-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

EdgeOne Pages Development Guide

EdgeOne Pages 开发指南

Develop full-stack applications on EdgeOne Pages — Edge Functions, Cloud Functions (Node.js / Go / Python), and Middleware.

在EdgeOne Pages上开发全栈应用——涵盖Edge Functions、Cloud Functions（Node.js/Go/Python）以及Middleware。

When to use this skill

何时使用本技能

Creating APIs, serverless functions, or backend logic on EdgeOne Pages
Adding middleware for request interception, redirects, auth guards, or A/B testing
Building full-stack apps with static frontend + server-side functions
Using KV Storage for edge-side persistent data
Setting up WebSocket endpoints (Node.js runtime)
Integrating Express, Koa, Gin, Echo, Flask, FastAPI, or Django on EdgeOne Pages
Debugging EdgeOne Pages runtime errors (function failures, middleware issues, KV problems)

Do NOT use for:

Deployment → use
```
edgeone-pages-deploy
```
skill
Next.js / Nuxt middleware or API routes → use the framework's own API, NOT the platform
```
middleware.js
```
Generic Express/Koa/Gin/Flask development outside an EdgeOne Pages project
Cloudflare Workers, Vercel Functions, or other platforms

在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或其他平台

How to use this skill (for a coding agent)

如何使用本技能（面向编码Agent）

Read the Decision Tree below to pick the correct runtime
Follow the Routing table to load the relevant reference file
Use the code patterns from that reference to implement the user's request

阅读下方的决策树选择正确的运行时
遵循路由表加载相关参考文件
使用参考文件中的代码模式实现用户需求

⛔ Critical Rules (never skip)

⛔ 关键规则（切勿跳过）

Choose the right runtime for the task. Follow the Decision Tree — never guess.
Edge Functions run on V8, NOT Node.js. Never use Node.js built-in modules (
```
fs
```
,
```
path
```
,
```
crypto
```
from Node) or npm packages in Edge Functions.
Cloud Functions support three runtimes: Node.js, Go, and Python. Place all function files under
```
cloud-functions/
```
directory. The platform detects the language by file extension (
```
.js
```
/
```
.ts
```
→ Node.js,
```
.go
```
→ Go,
```
.py
```
→ Python).
Node.js functions return a standard Web
Response
object, not
```
res.send()
```
— unless using Express/Koa via the
```
[[default]].js
```
pattern.
Go Handler mode requires
```
http.HandlerFunc
```
signature; Framework mode uses standard framework code with auto port/path adaptation.
Python entry files are identified by class/app patterns (
```
class handler(BaseHTTPRequestHandler)
```
,
```
app = Flask(...)
```
,
```
app = FastAPI(...)
```
). Other
```
.py
```
files are treated as helper modules.
Middleware is for lightweight request interception only. Never put heavy computation or database calls in middleware.
Always use
edgeone pages dev
for local development. Never run a separate dev server for functions — the CLI handles everything on port 8088.
Never configure
edgeone pages dev
as the
devCommand
in
edgeone.json
or as the
dev
script in
package.json
— this causes infinite recursion.
For framework projects (Next.js, Nuxt, etc.), use the framework's own middleware — NOT the platform
```
middleware.js
```
.

为任务选择合适的运行时。遵循决策树——切勿猜测。
Edge Functions运行在V8引擎上，而非Node.js。切勿在Edge Functions中使用Node.js内置模块（如Node的
```
fs
```
、
```
path
```
、
```
crypto
```
）或npm包。
Cloud Functions支持三种运行时：Node.js、Go和Python。所有函数文件需放置在
```
cloud-functions/
```
目录下。平台通过文件扩展名识别语言（
```
.js
```
/
```
.ts
```
→ Node.js，
```
.go
```
→ Go，
```
.py
```
→ Python）。
Node.js函数返回标准Web
Response
对象，而非
```
res.send()
```
——除非通过
```
[[default]].js
```
模式使用Express/Koa。
Go Handler模式要求
```
http.HandlerFunc
```
签名；框架模式使用标准框架代码，自动适配端口/路径。
Python入口文件通过类/应用模式识别（
```
class handler(BaseHTTPRequestHandler)
```
、
```
app = Flask(...)
```
、
```
app = FastAPI(...)
```
）。其他
```
.py
```
文件视为辅助模块。
Middleware仅用于轻量级请求拦截。切勿在中间件中执行重计算或数据库调用。
本地开发请始终使用
edgeone pages dev
。切勿为函数单独运行开发服务器——CLI会在8088端口处理所有内容。
切勿将
edgeone pages dev
配置为
edgeone.json
中的
devCommand
或
package.json
中的
dev
脚本——这会导致无限递归。
对于框架项目（Next.js、Nuxt等），使用框架自身的中间件——而非平台的
```
middleware.js
```
。

Technology Decision Tree

技术决策树

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

请求拦截 / 重定向 / 重写 / 权限校验 / A/B测试？
  → Middleware                                        → 阅读references/middleware.md

低延迟轻量级API（逻辑简单，无需npm）？
  → Edge Functions                                    → 阅读references/edge-functions.md

需要KV持久化存储？（⚠️ 需先在控制台启用KV）
  → Edge Functions + KV Storage                       → 阅读references/kv-storage.md

包含npm包/数据库/WebSocket的复杂后端？
  → Cloud Functions (Node.js)                         → 阅读references/node-functions.md

使用Express或Koa框架？
  → Cloud Functions (Node.js) + [[default]].js        → 阅读references/node-functions.md

基于Go（Gin/Echo/Chi/Fiber）的高性能API？
  → Cloud Functions (Go)                              → 阅读references/go-functions.md

基于Python（Flask/FastAPI/Django/Sanic）的API？
  → Cloud Functions (Python)                          → 阅读references/python-functions.md

纯静态站点，无服务器端逻辑？
  → 无需函数——直接部署静态文件

需要项目结构模板？
  → 阅读references/recipes.md

Runtime Comparison

运行时对比

Feature	Edge Functions	Cloud Functions (Node.js)	Cloud Functions (Go)	Cloud Functions (Python)	Middleware
Runtime	V8 (like CF Workers)	Node.js v20.x	Go 1.26+	Python 3.10	V8 (edge)
npm/packages	❌ Not supported	✅ Full npm ecosystem	✅ Go modules	✅ pip (auto-detect)	❌ Not supported
Max code size	5 MB	128 MB	128 MB	128 MB (incl. deps)	Part of edge bundle
Max request body	1 MB	6 MB	6 MB	6 MB	N/A (passes through)
Max CPU / wall time	200 ms CPU	120 s wall clock	120 s wall clock	120 s wall clock	Lightweight only
KV Storage	✅ Yes (global variable)	❌ No	❌ No	❌ No	❌ No
WebSocket	❌ No	✅ Yes	❌ No	❌ No	❌ No
Framework support	—	Express, Koa	Gin, Echo, Chi, Fiber	Flask, FastAPI, Django, Sanic	—
Use case	Lightweight APIs, edge compute	Complex APIs, full-stack	High-perf APIs, compiled speed	Data science, ML, rapid prototyping	Request preprocessing

特性	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	N/A（直接透传）
最大CPU/运行时间	200 ms CPU	120 s 挂钟时间	120 s 挂钟时间	120 s 挂钟时间	仅支持轻量级操作
KV Storage	✅ 支持（全局变量）	❌ 不支持	❌ 不支持	❌ 不支持	❌ 不支持
WebSocket	❌ 不支持	✅ 支持	❌ 不支持	❌ 不支持	❌ 不支持
框架支持	—	Express、Koa	Gin、Echo、Chi、Fiber	Flask、FastAPI、Django、Sanic	—
适用场景	轻量级API、边缘计算	复杂API、全栈应用	高性能API、编译级速度	数据科学、机器学习、快速原型开发	请求预处理

Cloud Functions — Language Comparison

Cloud Functions — 语言对比

Feature	Node.js	Go	Python
File extension	`.js` / `.ts`	`.go`	`.py`
Handler style	`export function onRequest(ctx)` → `Response`	`func Handler(w, r)` (Handler) or `func main()` (Framework)	`class handler(BaseHTTPRequestHandler)` or framework app instance
Framework mode	Express/Koa via `[[default]].js`	Gin/Echo/Chi/Fiber via entry `.go` file	Flask/FastAPI/Django via entry `.py` file
Dependency management	`package.json` (npm)	`go.mod` (auto)	`requirements.txt` + auto-detect
Dev modes	Handler / Framework	Handler / Framework	Handler / WSGI / ASGI

特性	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 / 框架	Handler / 框架	Handler / WSGI / ASGI

Routing

路由

Task	Read
Edge Functions (lightweight APIs, V8 runtime, KV Storage)	references/edge-functions.md
KV Storage (persistent key-value storage on edge)	references/kv-storage.md
Cloud Functions — Node.js (npm, database, 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 (redirects, rewrites, auth guards, A/B testing)	references/middleware.md
Project structure templates and common recipes	references/recipes.md
Debugging and troubleshooting	references/troubleshooting.md

任务	阅读文件
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

Project Setup (Quick Start)

项目设置（快速开始）

Initialize the project:

bash

edgeone pages init

Start local development:

bash

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

Link project (required for KV & env vars):

bash

edgeone pages link

Manage environment variables:

bash

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

Access env vars in functions via

context.env.KEY

(Node.js),

os.Getenv("KEY")

(Go), or

os.environ.get("KEY")

(Python).

For detailed project structures and recipes, see references/recipes.md.

初始化项目：

bash

edgeone pages init

启动本地开发：

bash

edgeone pages dev            # 在http://localhost:8088/上提供所有服务

关联项目（使用KV和环境变量必需）：

bash

edgeone pages link

管理环境变量：

bash

edgeone pages env pull       # 从控制台拉取到本地.env文件

在函数中通过

context.env.KEY

（Node.js）、

os.Getenv("KEY")

（Go）或

os.environ.get("KEY")

（Python）访问环境变量。

如需详细项目结构和方案，请查看references/recipes.md。