Next.js 运行时选择实战指南：默认 Node.js Runtime，仅在必要时启用 Edge——preguntas-entrevista-react 仓库 Agent 技能拆解

本文以 runtime-selection.md 为核心骨架，结合同目录下的 route-handlers.md、self-hosting.md、bundling.md 等最佳实践文档，系统讲解 Next.js App Router 中 Node.js Runtime 与 Edge Runtime 的选型原则、能力边界与检测清单，帮助你写出可部署、可维护、不踩运行时坑的页面与路由。

一、什么是 Next.js 运行时选择，为什么它值得单独写一条规范

在 Next.js App Router 中，"运行时"（Runtime）决定了页面、路由处理器、中间件等代码最终在哪个执行环境中运行。官方提供两类选择：

• Node.js Runtime：运行在 Node.js 服务器环境中，拥有完整的 Node.js API。
• Edge Runtime：运行在边缘网络（Edge Network）的轻量沙箱中，靠近用户、冷启动更小，但 API 能力受限。

在本仓库 .agents/skills/next-best-practices/ 这套 Next.js 最佳实践技能集中，运行时选择被列为一等规范条目（见 SKILL.md 中 "Runtime Selection" 一节），并在 CLAUDE.md 中被明确引用："Use the default Node.js runtime for new routes and pages. Only use Edge runtime if the project already uses it or there's a specific requirement."

这条规范的核心结论只有一句：默认使用 Node.js Runtime，仅在项目已在使用或存在明确需求时才考虑 Edge Runtime。

二、默认选择 Node.js Runtime：零配置即可获得完整能力

规范给出的第一条建议非常直接：新建路由和页面默认使用 Node.js 运行时，无需任何额外配置。因为 Node.js Runtime 本身就是 Next.js 的默认值，你什么都不写就是对的：

// Good: 默认运行时——不需要任何运行时配置（即使用 Node.js）
export default function Page() { ... }

// Caution: 仅当项目已在使用或确有特殊需求时才添加
export const runtime = 'edge'

注意第一段代码中 Page 没有 runtime 导出——这正是推荐的写法。只有当你确认需要 Edge 时才显式声明 export const runtime = 'edge'。

Node.js Runtime 的完整能力清单

规范列出了 Node.js Runtime 的核心优势，这些也是你在做技术决策时的判断依据：

• 完整的 Node.js API 支持：所有内置模块均可使用；
• 文件系统访问（fs）：读写本地文件、静态资源处理等；
• 完整的 crypto 支持：加解密、哈希、签名等；
• 数据库连接：可以直接连接 PostgreSQL、MySQL、Redis 等；
• 大多数 npm 包可用：无需担心包与运行时不兼容。

这条规则与同目录 route-handlers.md 中对"路由处理器运行环境"的描述互为印证：Route Handlers 运行在类似 Server Component 的环境中，可以使用 async/await、访问 cookies() 和 headers()、使用 Node.js API；反过来，不能使用 React hooks、不能使用 React DOM API、不能使用浏览器 API。

// app/api/users/route.ts —— 默认 Node.js 运行时即可完成典型的 API 逻辑
export async function GET() {
  const users = await getUsers()          // 可访问数据库
  return Response.json(users)
}

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

三、Edge Runtime：能力受限的"特种部队"

Edge Runtime 不是更高级的运行时，而是能力受限但位置更优的运行时。规范明确列出它的适用前提与局限：

适合使用 Edge 的场景：

• 有明确的边缘位置低延迟需求（如全球用户就近响应）；
• 需要更小的冷启动（Cold Start）；
• 有地理分布式部署需求。

Edge Runtime 的代价：

• API 受限：没有 fs 文件系统访问，crypto 能力受限；
• 依赖受限：并非所有 npm 包都能在 Edge 沙箱中运行。

自托管部署 的对照表中也给出了同样的结论：在自托管场景下，Edge Runtime 一行标注为 "Limited"（受限），并注明 "Some features Node-only"（部分特性仅 Node.js 支持）。也就是说，即便你想通过自托管来绕开平台限制，Edge Runtime 的能力天花板依然存在。

为什么 Edge 冷启动更小但 API 更少

Edge Runtime 本质上是把执行代码分发到离用户最近的边缘节点，避免每次请求都回源到中心服务器。换来的是地理延迟的降低和冷启动体积的减小，代价则是执行环境被裁剪——没有完整的文件系统、没有完整的加密库、没有完整的 Node 生态兼容面。理解这组"交易"（trade-off），是正确选型的前提。

四、添加 runtime = 'edge' 之前，先过这三道检测

规范专门给出了一个 "Detection"（检测）清单，要求在任何代码添加 runtime = 'edge' 之前逐项核对：

1. 项目是否已经在使用 Edge Runtime？——如果项目现有代码完全没有 edge 声明，新代码也不应率先引入，保持运行时策略的一致性；
2. 是否存在具体的延迟需求（specific latency requirement）？——"可能更快"不构成理由，必须有明确、可衡量的边缘低延迟诉求；
3. 所有依赖是否与 Edge 兼容（Edge-compatible）？——检查第三方包是否依赖 fs、crypto 等 Edge 不支持的能力。

如果无法确定，就用 Node.js Runtime。 这是规范的兜底原则：不确定时选择能力更完整、兼容性更好的默认运行时。

如何快速判断项目是否已在用 Edge

可以直接在代码库中搜索 runtime = 'edge' 或 runtime = "edge" 字样。如果搜索结果是零，说明项目当前全部走 Node.js Runtime，新代码应当跟随这一现状。这也是上面检测清单第 1 条的可执行落地方式。

五、运行时决策速查表

综合 runtime-selection.md 与仓库内相关技能文档，可以得到下面这张决策对照表：

维度	Node.js Runtime（默认）	Edge Runtime
配置方式	无需配置（默认值）	export const runtime = 'edge'
文件系统（fs）	✅ 完整支持	❌ 不支持
加密（crypto）	✅ 完整支持	⚠️ 受限
数据库连接	✅ 支持	❌ 通常不支持
npm 包兼容面	✅ 绝大多数可用	⚠️ 需逐包验证
冷启动	较大	更小
地理分布	依赖中心服务器	天然边缘就近
使用前提	无特殊要求	项目已在用或有明确延迟需求
自托管支持	✅ 完整（见 self-hosting.md 对照表）	⚠️ Limited，部分特性仅 Node.js

六、与运行时选择强相关的三个周边实践

运行时选择不是孤立决策，它与下面三个技能条目直接联动。一旦选错运行时，这些问题会立刻暴露。

1. 依赖兼容性：Edge 环境下 npm 包最容易翻车

bundling.md 专门处理第三方包的兼容问题。在 Edge Runtime 中，任何依赖浏览器 API（window、document、localStorage）或 Node 原生能力（fs）的包都可能直接报错，典型错误信号包括：

ReferenceError: window is not defined
ReferenceError: document is not defined
ReferenceError: localStorage is not defined
Module not found: Can't resolve 'fs'

解决思路有三条（与运行时选择配合使用）：

• 方案 1：标记为仅客户端（Client-Only）——用 next/dynamic 配合 ssr: false 只在浏览器加载：

  import dynamic from 'next/dynamic'
  
  const SomeChart = dynamic(() => import('some-chart-library'), {
    ssr: false,
  })
  

• 方案 2：从服务端打包中外部化——对带原生绑定（native bindings）的包如 sharp、bcrypt 使用：

  // next.config.js
  module.exports = {
    serverExternalPackages: ['problematic-package'],
  }
  

• 方案 3：客户端组件包装器——把整个使用场景包进一个 'use client' 组件。

实践提示：如果你的页面确实要用 Edge Runtime，务必先把所有依赖过一遍上述检查；反之，如果依赖里有 sharp、bcrypt、canvas 这类原生绑定包，几乎可以直接判定它不适合 Edge。

2. Server/Client 边界：Edge 不能成为绕过规则的借口

rsc-boundaries.md 强调：客户端组件不能是 async 函数，只有 Server Component 可以。跨边界的 props 必须是可序列化的（不能传函数、Date、Map/Set、类实例等）。运行时选择（Node.js vs Edge）解决的是"在哪个环境跑"，RSC 边界解决的是"哪些代码跑在服务端、哪些跑在客户端"，两者正交，但共同决定一段代码能否正常工作。例如一个依赖 fs 的数据读取逻辑，即使放在 async Server Component 里，也只在 Node.js Runtime 下可用。

3. 数据获取模式：读操作优先放 Server Component

data-patterns.md 给出的决策树同样隐含运行时假设：从 Server Component 直接读取数据（数据库直连或 fetch 外部 API）时，默认就在 Node.js Runtime 下执行；只有当你需要 REST API 供外部客户端消费、处理第三方 webhook 时才使用 Route Handler。这些模式默认场景下都不需要 Edge，进一步印证了"默认 Node.js"的合理性。

七、仓库实战佐证：Astro 静态站点与部署配置中的运行时决策

本仓库 preguntas-entrevista-react 本身是一个基于 Astro 7 + React 19（见 package.json）构建的 React 面试问答静态站点，构建配置见 astro.config.mjs（output: 'static'）。虽然站点本身不走 Next.js App Router，但仓库的 Agent 技能体系把 Next.js 最佳实践沉淀为可复用的规范文档（.agents/skills/next-best-practices/），而部署侧的真实配置恰好体现了"默认运行时 + 缓存策略"的工程思路：

• vercel.json 为全站配置了分层缓存：HTML 走 public, max-age=0, s-maxage=14400, stale-while-revalidate=86400，/content/、/quiz/ 下的 JSON 走 max-age=3600，静态图片资源走 max-age=86400, stale-while-revalidate=604800；
• 这说明：即便完全不需要 Edge Runtime，通过 CDN 缓存与 stale-while-revalidate 也能获得出色的边缘响应速度。

换句话说，Edge Runtime 不是低延迟的唯一答案——对绝大多数内容型站点，Node.js 运行时 + 合理的 CDN/缓存策略（如仓库 vercel.json 所示）已经足够，这也是"默认 Node.js Runtime"规范在真实工程中的有力佐证。

八、落地自检清单

把本文的核心规范压缩成一份可执行的提交前检查清单：

1. ✅ 新建页面/路由未添加 runtime = 'edge'，使用默认 Node.js Runtime；
2. ✅ 只有项目已有 Edge 用法或存在可衡量的延迟需求时才引入 Edge；
3. ✅ 引入 Edge 前逐项检查了依赖兼容性（无 fs 依赖、无原生绑定包、无浏览器 API 依赖）；
4. ✅ 无法确定时回退到 Node.js Runtime；
5. ✅ 数据读取优先放 Server Component，变更操作优先用 Server Action，外部 API 才用 Route Handler（详见 data-patterns.md）；
6. ✅ 部署时结合缓存策略（参考 vercel.json）获得边缘响应速度，而非依赖 Edge Runtime。

遵循这套规范，你的 Next.js 页面和路由将默认拥有最完整的 Node.js 能力、最广的 npm 生态兼容面，同时在确有边缘低延迟诉求时，仍能精准地局部启用 Edge Runtime——而不是把整个应用押注在一个受限沙箱上。

进一步阅读：本套 Next.js 最佳实践还涵盖 async-patterns.md（Next.js 15+ 异步 params/searchParams/cookies()）、error-handling.md（error.tsx、导航 API 不要包 try-catch）、functions.md（导航 hooks 与服务端函数）等，均与运行时选择配套使用。