边缘安全加速平台 EO Node Functions

概述
Node Functions 旨在简化您的后端开发流程，提供与前端项目无缝集成的 Node.js 运行时。它不仅支持处理传统的 HTTP 请求，还支持通过 WebSocket 协议进行实时双向通信。您可以在统一的项目中构建和部署动态 API 及复杂业务逻辑，平台将自动处理版本控制、构建与部署，并根据业务负载智能扩容，助您快速上线并持续交付。
优势
丰富的 Node.js 生态：可以直接使用 npm 生态中的海量模块，轻松集成各类第三方库和工具，满足复杂业务需求。
全栈开发体验：无需再将前后端项目分离，可在同一个项目中完成开发和部署，大幅提升协作效率。
路由即服务：通过文件系统即可定义 API 路由，实现后端逻辑的快速开发与部署，将后端服务像前端页面一样便捷管理。
支持实时通信：内置对 WebSocket 协议的支持，可轻松构建实时聊天、数据推送等需要持久化连接的现代 Web 应用。
快速开始
在项目的 ./node-functions/api 目录下新建 hello.js，使用以下示例代码创建您的第一个 Node Functions：
// 文件路径 ./node-functions/api/hello.js
// 访问路径 example.com/api/hello
export default function onRequest(context) {
  return new Response('Hello from Node Functions!');
}
注意：
在 ./node-functions 目录下创建 index.js，访问根路径则会进入到该函数而非首页。
在 ./node-functions 目录下创建 [[id]].js，除根路径外其他所有路径都会进入到该函数，需在函数内处理静态资源的返回。
我们建议您通过子目录来管理函数文件，如下示例在 ./node-functions/api 下创建 nodeinfo.js，用于返回 node 相关信息：
// 文件路径 ./node-functions/api/nodeinfo.js
// 访问路径 example.com/api/nodeinfo
import * 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 Functions 中使用 Express/Koa 开发时需注意，框架的路由只需要集中在一个函数文件里面处理，无需额外启动 HTTP Server 且需导出框架的实例。如下示例在 ./node-functions/express 下创建 [[default]].js，用于处理 express 的业务逻辑：
// 文件路径 ./node-functions/express/[[default]].js
import express from "express";
const app = express();
﻿
// 添加日志中间件
app.use((req, res, next) => {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  next();
});
﻿
// 添加根路由处理，访问路径 example.com/express/
app.get("/", (req, res) => {
  res.json({ message: "Hello from Express on Node Functions!" });
});
﻿
// 访问路径 example.com/express/users/123
app.get("/users/:id", (req, res) => {
  const { id } = req.params;
  res.json({ userId: id, message: `Fetched user ${id}` });
});
﻿
// 导出 express 实例
export default app;
函数调试
1. 安装 EdgeOne CLI：npm install -g edgeone。
2. 本地开发：在 Pages 代码项目下执行 edgeone pages dev，启动本地服务，进行函数调试。
3. 函数发布：代码推送到远端仓库，自动构建发布函数。
更多 EdgeOne CLI 的使用方式可参考 EdgeOne CLI。
路由
Node Functions 基于 /node-functions 目录结构生成访问路由。您可在项目仓库 /node-functions 目录下创建任意层级的子目录，参考下述示例。
...
node-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 映射到 /node-functions 文件，当客户端访问 URL 时将触发对应的文件代码被运行：
文件路径
路由
/node-functions/index.js
example.com/
/node-functions/hello-pages.js
example.com/hello-pages
/node-functions/helloworld.js
example.com/helloworld
/node-functions/api/users/list.js
example.com/api/users/list
/node-functions/api/users/geo.js
example.com/api/users/geo
/node-functions/api/users/[id].js
example.com/api/users/1024
/node-functions/api/visit/index.js
example.com/api/visit
/node-functions/api/[[default]].js
example.com/api/books/list
example.com/api/books/1024
example.com/api/...
说明：
路由尾部斜杠 / 是可选。/hello-pages 和 /hello-pages/ 将被路由到 /node-functions/hello-pages.js。
如果没有匹配到 Node Functions 路由，客户端请求将被路由到 Pages 对应的静态资源。
路由大小写敏感，/helloworld 将被路由到 /node-functions/helloworld.js，不能被路由到 /node-functions/HelloWorld.js。
动态路由
Node Functions 支持动态路由，上述示例中一级动态路径 /node-functions/api/users/[id].js，多级动态路径 /node-functions/api/[[default]].js。参考下述用法：
文件路径
路由
匹配
/node-functions/api/users/[id].js
example.com/api/users/1024
是
﻿
example.com/api/users/vip/1024
否
﻿
example.com/api/vip/1024
否
/node-functions/api/[[default]].js
example.com/api/books/list
是
﻿
example.com/api/1024
是
﻿
example.com/v2/vip/1024
否
框架内置路由
在涉及到 Express/Koa 框架的开发时，代码的编写与文件组织形式有几个要点需要注意。
Express/Koa 框架：
所有路由服务都收拢在一个函数文件内，且文件名必须是 [[]] 的格式，如 [[default]].js。
无需额外启动 HTTP Server 与设置端口监听。
必须导出框架实例否则构建器不会将其识别为函数 export default app。
例如，在目录 node-functions/express/* 下创建 express 应用，需以 [[default]].js 作为入口，且所有 express 相关路由都在 [[default]].js 里面：
node-functions 
└── express
    └── [[default]].js # express.js/koa.js 入口文件，包含框架内置路由定义
Function Handlers
使用 Function 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)
EventContext 对象描述
context 是传递给 Function Handlers 方法的对象，包含下述属性：
uuid：EO-LOG-UUID 代表了 EO 请求的唯一标识符。
params：动态路由 /node-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 对象描述
函数必须返回一个 Response 对象，来响应客户端的 HTTP 请求，包含 headers，status，body 等属性。
处理 WebSocket 请求
除了标准的 HTTP 请求外，Node Functions 还支持处理和响应 WebSocket 升级请求，以建立持久化的双向通信连接。
当函数接收到包含 Upgrade: WebSocket 头信息的 HTTP GET 请求时，您可以通过平台提供的能力将该连接升级为 WebSocket。升级后，即可在服务端监听和发送消息。具体可参考 Pages 的 AI Voice Chat 模板，了解如何实现一个实时语音 AI 对话服务。
使用限制
内容
限制
说明
代码包大小
128 MB
单个函数代码包大小最大支持 128 MB
请求 body 大小
6 MB
客户端请求携带 body 最大支持 6 MB
单次运行时长
30s
墙上时间
开发语言
Node.js
目前仅支持 Node.js，默认版本 v20.x
注意：
涉及到文件传输时，不建议存储需要长期保留的数据，推荐使用腾讯云 COS 来处理持久化的需求。
日志分析
Pages 控制台提供了基础的日志查看功能，开发者可以查看 Node Functions 调用的基本日志信息，通过日志快速发现并解决 API 调用中的异常或错误。详细指引可参见 日志分析。
示例模板
连接 MySQL 第三方数据库：
﻿预览地址﻿
﻿源码地址﻿
使用 Express 框架：
﻿预览地址﻿
﻿源码地址﻿
使用 Koa 框架：
﻿预览地址﻿
﻿源码地址﻿
AI 语音对话 (WebSocket 应用)：
﻿预览地址﻿
﻿源码地址﻿

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`)

文件路径	路由
/node-functions/index.js	example.com/
/node-functions/hello-pages.js	example.com/hello-pages
/node-functions/helloworld.js	example.com/helloworld
/node-functions/api/users/list.js	example.com/api/users/list
/node-functions/api/users/geo.js	example.com/api/users/geo
/node-functions/api/users/[id].js	example.com/api/users/1024
/node-functions/api/visit/index.js	example.com/api/visit
/node-functions/api/[[default]].js	example.com/api/books/list example.com/api/books/1024 example.com/api/...

文件路径	路由	匹配
/node-functions/api/users/[id].js	example.com/api/users/1024	是
		example.com/api/users/vip/1024	否
		example.com/api/vip/1024	否
/node-functions/api/[[default]].js	example.com/api/books/list	是
		example.com/api/1024	是
		example.com/v2/vip/1024	否

内容	限制	说明
代码包大小	128 MB	单个函数代码包大小最大支持 128 MB
请求 body 大小	6 MB	客户端请求携带 body 最大支持 6 MB
单次运行时长	30s	墙上时间
开发语言	Node.js	目前仅支持 Node.js，默认版本 v20.x

Node Functions

本页目录：

概述

优势

快速开始

函数调试

路由

Function Handlers

处理 WebSocket 请求

使用限制

日志分析

示例模板