Node.js
概述
Node.js 运行时支持 JavaScript 和 TypeScript 开发，可直接使用 npm 生态中的海量模块，适合构建 API 服务与全栈 Web 应用。
优势
丰富的 Node.js 生态：可以直接使用 npm 中的各类第三方库和工具，轻松集成数据库、AI、支付等服务，满足复杂业务需求。
全栈开发体验：无需再将前后端项目分离，可在同一个项目中完成开发和部署，大幅提升协作效率。
路由即服务：通过文件系统即可定义 API 路由，实现后端逻辑的快速开发与部署，将后端服务像前端页面一样便捷管理。
开发模式
Node.js 函数支持多种开发模式：
模式 | 适用场景 | 路由方式 | 框架依赖 |
Handler 模式 | 简单 API、Serverless 风格 | 文件系统路由（文件即路由） | 无（纯原生） |
框架模式 | 完整 Web 应用、RESTful API | 框架内置路由 | Express、Koa 等 |
快速开始
在项目的 ./cloud-functions/api 目录下新建 hello.js，使用以下示例代码创建您的第一个 Node.js 函数：
// ./cloud-functions/api/hello.jsexport default function onRequest(context) {return new Response('Hello from Node.js!');}
我们建议您通过子目录来管理函数文件，如下示例在 ./cloud-functions/api 下创建 nodeinfo.js，用于返回 node 相关信息：
// ./cloud-functions/api/nodeinfo.jsimport * as os from 'node:os'import { randomUUID, createHash } from 'node:crypto'export const onRequestGet = async ({ request }) => {const info = {nodeVersion: process.version,pid: process.pid,platform: os.platform(),url: request.url,}return new Response(JSON.stringify(info), {status: 200,headers: { 'Content-Type': 'application/json; charset=UTF-8' },})}
在 Node.js 函数中使用 Express/Koa 开发时需注意，框架的路由只需要集中在一个函数文件里面处理，无需额外启动 HTTP Server 且需导出框架的实例。如下示例在 ./cloud-functions/express 下创建 [[default]].js，用于处理 express 的业务逻辑：
// ./cloud-functions/express/[[default]].jsimport express from "express";const app = express();// 添加日志中间件app.use((req, res, next) => {console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);next();});app.get("/", (req, res) => {res.json({ message: "Hello from Express on Node.js!" });});app.get("/users/:id", (req, res) => {const { id } = req.params;res.json({ userId: id, message: `Fetched user ${id}` });});// 导出 express 实例export default app;
路由
Node.js 函数基于
/cloud-functions 目录结构生成访问路由。您可在项目仓库 /cloud-functions 目录下创建任意层级的子目录，参考下述示例。...cloud-functions├── index.js├── hello-pages.js├── helloworld.js├── api├── users├── list.js├── geo.js├── [id].js├── visit├── index.js├── [[default]].js...
上述目录文件结构，经 EdgeOne Pages 平台构建后将生成以下路由。这些路由将 Pages URL 映射到
/cloud-functions 文件，当客户端访问 URL 时将触发对应的文件代码被运行：文件路径 | 路由 |
/cloud-functions/index.js | example.com/ |
/cloud-functions/hello-pages.js | example.com/hello-pages |
/cloud-functions/helloworld.js | example.com/helloworld |
/cloud-functions/api/users/list.js | example.com/api/users/list |
/cloud-functions/api/users/geo.js | example.com/api/users/geo |
/cloud-functions/api/users/[id].js | example.com/api/users/1024 |
/cloud-functions/api/visit/index.js | example.com/api/visit |
/cloud-functions/api/[[default]].js | example.com/api/books/list、example.com/api/books/1024、example.com/api/... |
说明：
路由尾部斜杠 / 是可选。
/hello-pages 和 /hello-pages/ 将被路由到 /cloud-functions/hello-pages.js。如果 Node.js 路由跟静态资源路由冲突，客户端请求将优先被路由到静态资源。
路由大小写敏感，/helloworld 将被路由到 /cloud-functions/helloworld.js，不能被路由到 /cloud-functions/HelloWorld.js
路由匹配优先级
路由按以下优先级进行匹配（从高到低）：
1. 静态路由：精确匹配的路径优先（如
/api/users/list）2. 单级动态路由：
[param] 匹配单个路径段（如 /api/users/[id]）3. 多级动态路由（Catch-all）：
[[param]] 匹配一个或多个路径段（如 /api/[[default]]）同级别路由中，路径越长（越具体）优先级越高。
入口文件识别
并非所有
.js / .ts 文件都会被注册为路由。只有导出了 Function Handlers 方法（如 onRequest、onRequestGet 等）或导出了框架实例（如 Express app）的文件才会生成路由。不包含入口标识的
.js / .ts 文件将被视为辅助模块，会被复制到构建产物中供其他入口文件引用，但不会注册为独立路由。动态路由
Node.js 函数支持动态路由，上述示例中一级动态路径 /cloud-functions/api/users/[id].js，多级动态路径 /cloud-functions/api/[[default]].js。参考下述用法：
文件路径 | 路由 | 匹配 |
/cloud-functions/api/users/[id].js | example.com/api/users/1024 | 是 |
| example.com/api/users/vip/1024 | 否 |
| example.com/api/vip/1024 | 否 |
/cloud-functions/api/[[default]].js | example.com/api/books/list | 是 |
| example.com/api/1024 | 是 |
| example.com/v2/vip/1024 | 否 |
动态路由参数获取
在 Handler 模式下，可通过
context.params 获取动态路由参数：// ./cloud-functions/api/users/[id].jsexport function onRequestGet(context) {return new Response(`User id is ${context.params.id}`);}
框架内置路由
在涉及到 Express/Koa 框架的开发时，代码的编写与文件组织形式有几个要点需要注意。
Express/Koa 框架：
所有路由服务都收拢在一个函数文件内，且文件名必须是 [[]] 的格式，如 [[default]].js。
无需额外启动 HTTP Server 与设置端口监听
必须导出框架实例否则构建器不会将其识别为函数
export default app;例如，在目录 cloud-functions/express/* 下创建 express 应用，需以 [[default]].js 作为入口，且所有 express 相关路由都在 [[default]].js 里面：
cloud-functions└── express└── [[default]].js # express.js/koa.js 入口文件，包含框架内置路由定义
Function Handlers
使用 Functions Handlers 可为 Pages 创建自定义请求处理程序，以及定义 RESTful API 实现全栈应用。支持下述的 Handlers 方法：
Handlers 方法 | 描述 |
onRequest(context: EventContext): Response | Promise<Response> | 匹配 HTTP Methods ( GET, POST, PATCH, PUT, DELETE, HEAD, OPTIONS) |
onRequestGet(context: EventContext): Response | Promise<Response> | 匹配 HTTP Methods ( GET) |
onRequestPost(context: EventContext): Response | Promise<Response> | 匹配 HTTP Methods ( POST) |
onRequestPatch(context: EventContext): Response | Promise<Response> | 匹配 HTTP Methods ( PATCH) |
onRequestPut(context: EventContext): Response | Promise<Response> | 匹配 HTTP Methods ( PUT) |
onRequestDelete(context: EventContext): Response | Promise<Response> | 匹配 HTTP Methods ( DELETE) |
onRequestHead(context: EventContext): Response | Promise<Response> | 匹配 HTTP Methods ( HEAD) |
onRequestOptions(context: EventContext): Response | Promise<Response> | 匹配 HTTP Methods ( OPTIONS) |
基本用法
Handler 函数通过导出
onRequest 方法处理所有 HTTP 请求：// ./cloud-functions/api/hello.jsexport default function onRequest(context) {return new Response('Hello, world!', {headers: { 'Content-Type': 'text/plain' },});}
处理多种请求方法
通过导出不同的 Handler 方法，可以分别处理不同类型的 HTTP 请求：
// ./cloud-functions/api/users/index.jsexport function onRequestGet(context) {return new Response(JSON.stringify({ users: [] }), {headers: { 'Content-Type': 'application/json' },});}export function onRequestPost(context) {return context.request.json().then(data => {return new Response(JSON.stringify({ message: 'Created', data }), {status: 201,headers: { 'Content-Type': 'application/json' },});});}export function onRequestDelete(context) {return new Response(null, { status: 204 });}
获取查询参数
// ./cloud-functions/api/search.jsexport function onRequestGet(context) {const url = new URL(context.request.url);const name = url.searchParams.get('name') || 'Guest';return new Response(JSON.stringify({ hello: name }), {headers: { 'Content-Type': 'application/json' },});}
EventContext 对象描述
context 是传递给 Function Handlers 方法的对象，包含下述属性：
uuid：EO-LOG-UUID 代表了 EO 请求的唯一标识符
params：动态路由
/cloud-functions/api/users/[id].js 参数值export function onRequestGet(context) {return new Response(`User id is ${context.params.id}`);}
env：Pages 环境变量
clientIp：客户端 IP 地址
server：
region: 部署地的区域编码
requestId: 请求 ID，用于日志跟踪
geo：客户端地理位置信息
Response 对象描述
示例模板
连接 MySQL 三方数据库：
使用 Express 框架：
使用 Koa 框架：
