SuperAPI AI 工具集

netlify-server

部署与运维

查看项目

更新于 11-10 23:00

技能介绍

用途

Netlify Server 用于在 Netlify 上运行长期存活的 Node.js 后端服务,适合需要自定义 HTTP 服务器、WebSocket 或流式响应的场景。早期访问阶段(Early Access)API 可能变化。

主要能力

  • 支持多种入口形式:处理函数(与 Netlify Functions 签名相同)、可获取应用(Fetchable,如 Hono)、Express/Connect 应用、自启动的 HTTP 服务器(需在 10 秒内监听 PORT)。
  • 支持 WebSocket 升级(通过 upgradeWebSocket 或自启动服务器上的 ws)。
  • 支持服务器发送事件(SSE)和流式响应。
  • 提供生命周期钩子:onStart、onShutdown、onHealthCheck,以及 getWebSockets、getContext、waitUntil 等工具。
  • 支持边缘缓存控制(通过响应头 Netlify-CDN-Cache-Control),支持 stale-while-revalidate、按查询/请求头/语言/国家/cookie 变化缓存键、按站点或缓存标签失效,每次部署会使旧缓存失效。
  • 提供请求上下文:地理信息、IP、URL、requestId、cookies、deploy、site、account、server、user、waitUntil 等。
  • 可通过入口文件的 config 导出或 netlify.toml 配置 path、excludedPath、region、size、scale、includedFiles 等。

使用方式

  1. 安装包:npm install @netlify/server。
  2. 在项目中使用一个服务器入口文件:netlify/server/index.ts、.mts、.js 或 .mjs(只能存在一个,否则构建失败)。
  3. 根据默认导出的类型选择运行方式(详见文档表格)。
  4. 本地开发运行 netlify dev(Netlify CLI 27.17.0+),Vite 插件不运行服务器。
  5. 日志可通过 netlify logs --source server 查看。

适用场景

  • 需要长期运行后端逻辑的新项目。
  • 需要 WebSocket 或 SSE 的实时应用。
  • 需要自定义 HTTP 处理、中间件或框架(如 Express、Fastify、Hono)的场景。

限制

  • 早期访问阶段免费,正式发布后将按预留内存(GB-小时)和活跃 CPU(vCPU-小时)计费;每个请求计入 Web 请求计量。
  • 需要 Node.js 24+ 和 Netlify CLI 27.17.0+。
  • 响应超时 20 秒内需发送状态码和头,否则返回 502;冷启动时间计入。
  • 请求持续时间(含 WS/SSE)30 分钟,Pro/Business/Enterprise 为 2 小时。
  • 出站连接空闲 60 秒后关闭,TCP keepalive 不计入。
  • 实例生命周期 8 小时;实例数:基于信用的 Pro/Enterprise 为 3,Free/Personal 为 1。
  • 并发:small 32、medium 64、large 128 个请求每实例;SSE/流占用槽位,WebSocket 不占用但每实例有限制。
  • 空闲 5 分钟后缩容到零;setInterval 不会阻止缩容。
  • 内存和 /tmp 为每实例独立,缩容、部署、平台维护时丢失。
  • 不支持原始 TCP,仅 Node.js HTTP 服务器。
  • 全栈框架(Next.js、Astro、Nuxt、SvelteKit、React Router、TanStack Start)不能运行在 Netlify Server 上。
  • 路由顺序:边缘函数、重定向/重写、静态文件、函数、服务器;静态文件优先。
  • 本地开发与生产存在差异:单实例、忽略 path/excludedPath、无限制、5 秒关闭、Windows 无 SIGTERM、无健康钩子。
  • 健康钩子本地不运行;健康钩子抛异常不会停止实例。
  • 自启动服务器需在启动钩子完成后 10 秒内监听 PORT,否则启动失败。
  • 保留端口 53 和 15000–15099;.netlify/server/ 路径保留。