IGA Pages Functions 是 IGA Pages 平台提供的基于文件系统的 Node.js Serverless Functions 能力。开发者只需在项目根目录下创建 api/ 目录，并在其中放置 .js 文件，即可将每个文件自动映射为一条可公开访问的 HTTP 路由，整个过程无需编写路由配置文件，也无需手动注册路由表。

Functions 功能简介 #

IGA Pages Functions 的设计理念是"约定优于配置"：文件的存放路径决定了对外暴露的 URL 路径，函数的导出方式决定了请求的处理逻辑。这种方式显著降低了搭建后端 API 服务的门槛，使前端开发者也能快速构建轻量级的服务端接口。
核心特性：

• 零配置路由：文件路径即 URL 路径，无需手动注册路由或编写额外的配置文件
• 三种路由模式：静态路由、动态路由、Catch-all 路由，能够灵活覆盖绝大多数业务场景
• 内置请求解析：运行时自动解析查询参数、路由参数、Cookie 以及请求体，开箱即用
• 框架兼容：支持将 Express、Koa 等主流 Node.js 框架的应用实例直接作为 Serverless Function 运行，大部分场景无需改动

快速开始 #

只需两步即可在本地运行第一个 Function，验证整个开发流程。

1. 创建 Function 文件。
   在项目根目录下新建 api/hello.js 文件，写入以下内容。该函数处理 GET 请求，返回一段 JSON 格式的问候信息：

   export async function GET(request) {
     return Response.json({ message: "Hello from IGA Pages!" });
   }
   

2. 启动本地开发服务。
   首先安装 IGA Pages 命令行工具，然后启动本地开发服务器：

   npm install -g @iga-pages/cli
   iga pages dev
   

   服务启动后，在浏览器或任意 HTTP 客户端中访问 http://localhost:3000/api/hello，即可看到如下 JSON 响应：

   {
     "message": "Hello from IGA Pages!"
   }
   

至此，你已经成功创建并运行了第一个 IGA Pages Function。

路由规则 #

IGA Pages Functions 的路由系统完全基于文件系统驱动，api/ 目录下的文件夹层级和文件名直接决定了对外暴露的 URL 路径结构。开发者无需维护独立的路由配置文件，只要合理组织文件结构，即可自动生成清晰的 API 路由。

目录结构与 URL 映射 #

以下是一个典型的项目目录结构，以及每个文件对应的 HTTP 路由路径：

api/
├── index.js                → /api
├── hello.js                → /api/hello
├── users/
│   ├── list.js             → /api/users/list
│   └── [id].js             → /api/users/:id
├── [id].js                 → /api/:id
├── group/
│   └── [id]/
│       └── detail.js       → /api/group/:id/detail
└── [[default]].js          → /api/:default*

可以看到，文件的嵌套层级与 URL 的路径层级完全一致。文件夹名称构成路径中的固定片段，而使用方括号包裹的文件名或文件夹名则构成动态参数片段。

静态路由、动态路由与 Catch-all 路由 #

IGA Pages Functions 支持三种路由类型，它们的命名规则和匹配行为各不相同：

补充说明：

• 尾部斜杠可选 — /api/hello 与 /api/hello/ 在路由匹配时视为等价，两者均会命中 api/hello.js。
• 动态参数必填 — 动态路由 [param] 要求请求路径中必须包含对应的路径片段。例如 api/users/[id].js 不会匹配 /api/users，因为缺少 id 参数。
• Catch-all 路由兜底 — [[param]] 路由可以匹配空路径，也可以匹配任意深度的路径，因此非常适合作为兜底路由使用，常用于框架集成场景。

路由匹配优先级规则 #

当一个请求路径可能同时匹配多条路由规则时，IGA Pages 按照以下优先级从高到低依次尝试匹配。一旦命中，即停止后续匹配：

• 静态路由优先级最高 — 精确匹配的路径总是被优先选中
• 动态路由次之 — 当没有精确匹配的静态路由时，尝试动态参数匹配
• Catch-all 路由优先级最低 — 仅在前两种类型均未命中时才生效

这一优先级设计确保了路由行为的可预测性：具体的路由总是优先于模糊的路由。

路由匹配完整示例 #

下表基于路由规则中的目录结构，列出了各种请求路径的匹配结果，帮助开发者直观理解路由匹配逻辑：

函数处理器（Function Handlers） #

Function Handler 是 IGA Pages Functions 的核心概念。每个 .js 文件通过导出函数来定义请求处理逻辑。IGA Pages 运行时在接收到 HTTP 请求后，根据路由规则定位到目标文件，并调用其导出的处理函数。

Fetch Handler 函数（推荐） #

推荐使用基于 Web 标准 Request / Response 的 Fetch Handler 写法。通过 export default 导出一个包含 fetch 方法的对象，运行时会把入站请求封装为标准 Request 对象传入，由 fetch 方法统一处理并返回标准 Response 对象。这种写法与 Web 平台规范保持一致，便于在不同运行时之间迁移与复用：

// 文件：api/users/[id].js
export default {
  async fetch(request) {
    const { id } = request.params;
    return Response.json({ userId: id });
  },
};

具名 HTTP 方法 #

同样基于 Web 标准 Request / Response，可以按 HTTP 方法分别导出同名的异步函数，运行时会根据请求方法调用对应的处理函数。支持 GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS：

export async function GET(request) {
  const { id } = request.params;
  return Response.json({ userId: id });
}

export async function POST(request) {
  const body = await request.json();
  return Response.json({ created: body }, { status: 201 });
}

在 Functions 中集成 Node.js 框架 #

对于已有 Express 或 Koa 项目的开发者，IGA Pages Functions 支持将整个框架应用实例直接作为 Serverless Function 部署。框架内部定义的所有路由集中在一个 Function 文件中处理，由 IGA Pages 运行时负责网络层的管理，开发者无需自行启动 HTTP Server。
关于框架集成的完整配置细节和进阶用法，请参见IGA Pages 框架指南。

框架集成的约束与规范 #

在进行框架集成时，必须严格遵守以下三项约束，否则部署可能失败或路由无法正确匹配：

集成 Express 示例 #

以下示例展示了如何在 IGA Pages Functions 中运行一个 Express 应用：

// api/[[default]].js
import express from "express";

const app = express();
app.use(express.json());

app.get("/api/hello", (req, res) => {
  res.json({ message: "Hello from Express on IGA Pages!" });
});

app.post("/api/users", (req, res) => {
  const { name } = req.body;
  res.status(201).json({ created: true, name });
});

// 重要：不要调用 app.listen()，直接导出应用实例
export default app;

集成 Koa 示例 #

以下示例展示了如何在 IGA Pages Functions 中运行一个 Koa 应用：

// api/[[default]].js
import Koa from "koa";
import Router from "@koa/router";
 
const app = new Koa();
const router = new Router();

router.get("/api/hello", (ctx) => {
  ctx.body = { message: "Hello from Koa on IGA Pages!" };
});

router.post("/api/users", (ctx) => {
  ctx.status = 201;
  ctx.body = { created: true };
});

app.use(router.routes());
app.use(router.allowedMethods());

// 重要：不要调用 app.listen()，直接导出应用实例
export default app;