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, Node Functions, and Middleware.

在 EdgeOne Pages 上开发全栈应用——涵盖 Edge Functions、Node Functions 及 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
Integrating Express or Koa frameworks on EdgeOne Pages

Do NOT use for:

Deployment → use
```
edgeone-pages-deploy
```
skill
Next.js / Nuxt middleware → use the framework's own middleware API, NOT the platform
```
middleware.js
```

在 EdgeOne Pages 上创建 API、无服务器函数或后端逻辑
添加用于请求拦截、重定向、权限校验或 A/B 测试的中间件
构建静态前端 + 服务端函数的全栈应用
使用 KV Storage 实现边缘端持久化数据存储
搭建 WebSocket 端点
在 EdgeOne Pages 上集成 Express 或 Koa 框架

请勿用于：

部署 → 使用
```
edgeone-pages-deploy
```
技能
Next.js / Nuxt 中间件 → 使用框架自带的中间件 API，而非平台的
```
middleware.js
```

How to use this skill (for a coding agent)

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

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

阅读下方的决策树以选择正确的运行时
遵循路由表读取相关模块文件
使用该模块的代码模式实现用户需求

⛔ Critical Rules (MUST follow)

⛔ 重要规则（必须遵守）

Choose the right runtime for the task. Follow the Decision Tree below — never guess.
Edge Functions run on V8, NOT Node.js. Do NOT use Node.js built-in modules (
```
fs
```
,
```
path
```
,
```
crypto
```
from Node) or npm packages in Edge Functions.
Node Functions MUST return a standard Web
Response
object, not
```
res.send()
```
— unless using Express/Koa via the
```
[[default]].js
```
pattern.
Middleware is for lightweight request interception ONLY. Never put heavy computation or database calls in middleware.
Always use
edgeone pages dev
for local development. Do NOT 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
. For example, in Next.js projects use
```
middleware.ts
```
at the project root with Next.js middleware API (
```
NextRequest
```
,
```
NextResponse
```
), NOT the EdgeOne Pages
```
middleware.js
```
format. The platform middleware file is only for non-framework or pure static projects.

为任务选择正确的运行时。请遵循下方的决策树——切勿猜测。
Edge Functions 运行在 V8 引擎上，而非 Node.js。请勿在 Edge Functions 中使用 Node.js 内置模块（如 Node 的
```
fs
```
、
```
path
```
、
```
crypto
```
）或 npm 包。
Node Functions 必须返回标准 Web
Response
对象，而非
```
res.send()
```
——除非通过
```
[[default]].js
```
模式使用 Express/Koa。
Middleware 仅用于轻量请求拦截。切勿在中间件中执行重计算或数据库调用。
本地开发请始终使用
edgeone pages dev
。请勿为函数单独运行开发服务器——CLI 会在 8088 端口处理所有内容。
切勿将
edgeone pages dev
配置为
edgeone.json
中的
devCommand
或
package.json
中的
dev
脚本——这会导致无限递归。
对于框架项目（Next.js、Nuxt 等），请使用框架自带的中间件——而非平台的
middleware.js
。例如，在 Next.js 项目中，请在项目根目录使用
```
middleware.ts
```
及 Next.js 中间件 API（
```
NextRequest
```
、
```
NextResponse
```
），而非 EdgeOne Pages 的
```
middleware.js
```
格式。平台中间件文件仅适用于非框架或纯静态项目。

Technology Decision Tree

技术决策树

Use this to pick the correct approach for each user request:

User needs request interception / redirect / rewrite / auth guard / A/B test?
  → Middleware                                → read middleware.md

User needs a lightweight API with ultra-low latency (simple logic, no npm)?
  → Edge Functions                            → read edge-functions.md

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

User needs complex backend logic / npm packages / database / WebSocket?
  → Node Functions                            → read node-functions.md

User needs Express or Koa framework?
  → Node Functions with [[default]].js entry  → read node-functions.md

User has a pure static site with no server-side logic?
  → No functions needed — just deploy static files

Need a project structure template?
  → read recipes.md

使用以下决策树为每个用户需求选择正确的实现方式：

User needs request interception / redirect / rewrite / auth guard / A/B test?
  → Middleware                                → read middleware.md

User needs a lightweight API with ultra-low latency (simple logic, no npm)?
  → Edge Functions                            → read edge-functions.md

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

User needs complex backend logic / npm packages / database / WebSocket?
  → Node Functions                            → read node-functions.md

User needs Express or Koa framework?
  → Node Functions with [[default]].js entry  → read node-functions.md

User has a pure static site with no server-side logic?
  → No functions needed — just deploy static files

Need a project structure template?
  → read recipes.md

Runtime Comparison

运行时对比

Feature	Edge Functions	Node Functions	Middleware
Runtime	V8 (like Cloudflare Workers)	Node.js v20.x	V8 (edge)
npm packages	❌ Not supported	✅ Full npm ecosystem	❌ Not supported
Max code size	5 MB	128 MB	Part of edge bundle
Max request body	1 MB	6 MB	N/A (passes through)
Max CPU / wall time	200 ms CPU	120 s wall clock	Lightweight only
KV Storage	✅ Yes (global variable)	❌ No	❌ No
WebSocket	❌ No	✅ Yes	❌ No
Use case	Lightweight APIs, edge compute	Complex APIs, full-stack	Request preprocessing

特性	Edge Functions	Node Functions	Middleware
运行时	V8（类似 Cloudflare Workers）	Node.js v20.x	V8（边缘节点）
npm 包支持	❌ 不支持	✅ 完整 npm 生态	❌ 不支持
最大代码体积	5 MB	128 MB	属于边缘打包产物
最大请求体大小	1 MB	6 MB	N/A（直接透传）
最大 CPU/运行时间	200 ms CPU	120 s 时钟时间	仅支持轻量操作
KV Storage	✅ 支持（全局变量）	❌ 不支持	❌ 不支持
WebSocket	❌ 不支持	✅ 支持	❌ 不支持
适用场景	轻量 API、边缘计算	复杂 API、全栈应用	请求预处理

Routing

路由

Task	Read
Edge Functions (lightweight APIs, V8 runtime, KV Storage)	edge-functions.md
KV Storage (persistent key-value storage on edge)	kv-storage.md
Node Functions (npm, database, Express/Koa, WebSocket)	node-functions.md
Middleware (redirects, rewrites, auth guards, A/B testing)	middleware.md
Project structure templates and common recipes	recipes.md
Debugging and troubleshooting	troubleshooting.md

任务	参考文档
Edge Functions（轻量 API、V8 运行时、KV Storage）	edge-functions.md
KV Storage（边缘端持久化键值存储）	kv-storage.md
Node Functions（npm、数据库、Express/Koa、WebSocket）	node-functions.md
Middleware（重定向、重写、权限校验、A/B 测试）	middleware.md
项目结构模板及常见实践	recipes.md
调试与故障排查	troubleshooting.md

Project Setup

项目搭建

1. Initialize the project

1. 初始化项目

bash

edgeone pages init

The CLI will guide you to create

edge-functions/

and/or

node-functions/

directories with sample functions.

bash

edgeone pages init

CLI 会引导你创建

edge-functions/

和/或

node-functions/

目录，并包含示例函数。

2. Standard project structure

2. 标准项目结构

my-project/
├── edge-functions/          # Edge Functions (V8 runtime)
│   └── api/
│       ├── hello.js         # → /api/hello
│       ├── users/
│       │   ├── list.js      # → /api/users/list
│       │   ├── [id].js      # → /api/users/:id (dynamic)
│       │   └── index.js     # → /api/users
│       └── [[default]].js   # → /api/* (catch-all)
├── node-functions/          # Node Functions (Node.js runtime)
│   └── api/
│       ├── data.js          # → /api/data
│       ├── ws.js            # → /api/ws (WebSocket)
│       └── [[default]].js   # → /api/* (Express/Koa entry)
├── middleware.js             # Middleware (runs before all requests)
├── edgeone.json              # Project config (auto-generated)
├── package.json
├── index.html                # Static frontend
└── ...

my-project/
├── edge-functions/          # Edge Functions（V8 运行时）
│   └── api/
│       ├── hello.js         # → /api/hello
│       ├── users/
│       │   ├── list.js      # → /api/users/list
│       │   ├── [id].js      # → /api/users/:id（动态路由）
│       │   └── index.js     # → /api/users
│       └── [[default]].js   # → /api/*（兜底路由）
├── node-functions/          # Node Functions（Node.js 运行时）
│   └── api/
│       ├── data.js          # → /api/data
│       ├── ws.js            # → /api/ws（WebSocket）
│       └── [[default]].js   # → /api/*（Express/Koa 入口）
├── middleware.js             # Middleware（在所有请求前运行）
├── edgeone.json              # 项目配置（自动生成）
├── package.json
├── index.html                # 静态前端
└── ...

3. Local development

3. 本地开发

bash

edgeone pages dev

Serves everything on
```
http://localhost:8088/
```
— frontend and functions unified, no proxy needed.
Hot reload is supported; avoid restarting the CLI frequently (Edge Functions has startup count limits).
Use
```
console.log()
```
in functions for debugging — logs appear in the terminal.

bash

edgeone pages dev

将所有内容托管在
```
http://localhost:8088/
```
—— 前端与函数统一托管，无需代理。
支持热重载；请避免频繁重启 CLI（Edge Functions 有启动次数限制）。
在函数中使用
```
console.log()
```
进行调试——日志会显示在终端中。

4. Link project (for KV & env vars)

4. 关联项目（用于 KV 存储与环境变量）

bash

edgeone pages link

Required if you need KV Storage access or want to sync environment variables from the console.

bash

edgeone pages link

如果需要访问 KV Storage 或同步控制台中的环境变量，必须执行此步骤。

5. Environment variables

5. 环境变量

bash

edgeone pages env ls            # List all
edgeone pages env pull          # Pull to local .env
edgeone pages env pull -f .env.prod  # Pull to specific file
edgeone pages env add KEY value # Add
edgeone pages env rm KEY        # Remove

Access in functions via

context.env.KEY

bash

edgeone pages env ls            # 列出所有环境变量
edgeone pages env pull          # 拉取到本地 .env 文件
edgeone pages env pull -f .env.prod  # 拉取到指定文件
edgeone pages env add KEY value # 添加环境变量
edgeone pages env rm KEY        # 删除环境变量

在函数中可通过

context.env.KEY

访问环境变量。