国际站
    控制台
    • 产品简介
    • 快速开始
      • 导入 Git 仓库
      • 从模板开始
      • 直接上传
      • 从 AI 开始
    • 框架指南
      • 前端
      • 后端
      • 全栈
        • Next.js
    • 项目指南
      • 项目管理
      • edgeone.json
      • 缓存配置
      • 错误码
    • 构建指南
    • 部署指南
      • 概览
      • 触发部署
      • 管理部署
      • 部署按钮
      • 使用 Github Action
      • 使用 CNB 插件
      • 使用 IDE 插件
      • 使用 CodeBuddy IDE
    • 域名管理
      • 概览
      • 自定义域名
      • 配置 HTTPS 证书
      • 如何配置 DNS 的 CNAME 记录
    • Pages Functions
      • 概览
      • Edge Functions
      • Node Functions
    • 日志分析
    • KV 存储
    • 边缘 AI
    • API Token
    • EdgeOne CLI
    • Pages MCP
    • 集成指南
      • AI
        • 对话型大模型集成
        • 图片大模型集成
      • 数据库
        • Supabase 集成
        • Pages KV 集成
      • 电商
        • WooCommerce 集成
        • Shopify 集成
      • 支付
        • Stripe 集成
        • Paddle 集成指南
      • CMS
        • Sanity 集成
        • Contentful 集成
        • WordPress 集成
      • 身份验证
        • Supabase 集成
        • Clerk 集成
    • 最佳实践
      • 使用边缘AI模型快速搭建对话型AI站点
      • 使用 WordPress + WooCommerce 和 GatsbyJS 搭建电商平台
      • 使用 Supabase 和 Stripe 搭建 SaaS 站点
      • 如何快速搭建公司品牌站点
      • 如何快速搭建博客站点
      • 使用通用大模型快速搭建AI应用
    • 迁移指南
      • 从 Vercel 迁移至 EdgeOne Pages:优化您在中国区域的网站部署
      • 从 Cloudflare Pages 迁移至 EdgeOne Pages:优化您在中国区域的网站部署
      • 从 Netlify 迁移至 EdgeOne Pages:优化您在中国区域的网站部署
    • 排障指南
    • 常见问题
    • 联系我们
    • 产品动态

    Node Functions

    概述

    Node Functions 旨在简化您的后端开发流程,提供与前端项目无缝集成的 Node.js 运行时。您可以在统一的项目中构建和部署动态 API 及复杂业务逻辑,平台将自动处理版本控制、构建与部署,并根据业务负载智能扩容,助您快速上线并持续交付。
    

    优势

    丰富的 Node.js 生态:可以直接使用 npm 生态中的海量模块,轻松集成各类第三方库和工具,满足复杂业务需求。
    全栈开发体验:无需再将前后端项目分离,可在同一个项目中完成开发和部署,大幅提升协作效率。
    路由即服务:通过文件系统即可定义 API 路由,实现后端逻辑的快速开发与部署,将后端服务像前端页面一样便捷管理。
    

    快速开始

    在项目的 ./node-functions 目录下新建 hello.js,使用以下示例代码创建您的第一个 Node Functions:
    // 文件路径 ./node-functions/hello.js
    // 访问路径 example.com/hello
    export default function onRequest(context) {
    return new Response('Hello from Node Functions!');
    }
    注意:
    若在 ./node-functions 目录下通过 index.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 的使用方式可参考文档
    

    路由

    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

    使用 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)
    
    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 等属性。
    

    使用限制

    内容
    限制
    说明
    代码包大小
    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 框架: