netlify-frameworks

将框架相关的深入内容交给本技能中的指南：references/astro.md、references/nextjs.md、references/nuxt.md、references/sveltekit.md、references/tanstack.md、references/vite.md。

环境变量：现代规则（请先阅读）

环境变量的值会在构建时注入。任何更改（客户端或服务端）都需要重新部署——在 UI/CLI 中编辑变量不会影响线上站点或已部署的函数，除非运行新的构建。

切勿为机密信息使用客户端前缀。 带客户端前缀的变量会被内联到浏览器包中： VITE_、NEXT_PUBLIC_、PUBLIC_、NUXT_PUBLIC_、REACT_APP_、GATSBY_、VUE_APP_。

各框架的客户端嵌入前缀：CRA REACT_APP_、Gatsby GATSBY_、Next NEXT_PUBLIC_、Nuxt NUXT_ENV_、Vue CLI VUE_APP_。

作用域： 构建时访问需要 Builds 作用域；SSR/DSG 运行时访问则需要 Functions 和 Builds 两者。netlify.toml 仅在构建期间读取——函数无法在运行时读取它；请在 UI/CLI/API 中设置运行时变量。

Netlify 构建变量不能用作 UI 或 netlify.toml 的 env 部分中的值。请在构建命令之前内联设置：

[build]
  command = "REACT_APP_CONTEXT=$CONTEXT npm run build"

SPA 重定向与 SSR 全匹配规则的隐患

SPA（React、Vue CLI、Vite、SPA 模式下的 Nuxt）需要通过重写来为 pushState 提供 index.html：

/* /index.html 200

采用 SSR 适配器时，请移除所有 SPA 全匹配规则。 遗留的 /* → /index.html 200 会悄无声息地为 SSR 页面和 API 路由提供静态 index.html——用户重定向的优先级高于适配器生成的路由。

使用平台模拟进行本地开发（无需 Netlify CLI）

基于 Vite 的框架可在开发服务器中模拟 Netlify 原语（函数、边缘函数、blobs、Netlify Database、Cache API、Image CDN、重定向/重写、标头、环境变量、AI Gateway）：

框架	插件/模块	运行命令
Astro (5.12+)	内置（自动加载 Netlify Vite 插件）	astro dev
Nuxt	@netlify/nuxt	nuxt dev
React Router	@netlify/vite-plugin	react-router dev
SolidStart 2	@netlify/vite-plugin	vite dev
TanStack Start	@netlify/vite-plugin-tanstack-start	（vite）
Vite	@netlify/vite-plugin	npx vite

以下情况仍需使用 netlify dev（Netlify CLI）：Gatsby 生成的函数（先运行 netlify build）、Angular SSR 本地测试（netlify serve），以及没有 Vite 插件的框架。

netlify dev 注意事项： 如果 [dev] 中同时设置了自定义 command 和 targetPort，必须设置 framework = "#custom"——否则检测器会运行，并悄无声息地忽略你的自定义命令。

各框架的构建设置

框架	构建命令	发布目录
Angular（标准）	ng build --prod	dist/YOUR_PROJECT_NAME
Astro	astro build	dist
Create React App	react-scripts build	build
Eleventy	eleventy	_site
Gatsby	gatsby build	public
Hugo	hugo	public
Hydrogen	remix vite:build	dist/client
Next.js（SSR/混合）	next build	.next
Next.js（静态导出）	next build && next export	out（NETLIFY_NEXT_PLUGIN_SKIP=true）
Nuxt 3	nuxt build	dist
Nuxt 2	nuxt generate	dist
React Router	react-router build	build/client
Remix（Vite）	remix vite:build	build/client
SolidStart 2（Vite 插件）	vite build	dist/client
SolidStart 2（Nitro）	vite build	dist
SolidStart 1.x	vinxi build	dist
SvelteKit	vite build	build
TanStack Start (1.132.0+)	vite build	dist/client
Vite	vite build	dist
Vue CLI	vue-cli-service build	dist

检测结果会推荐这些设置；可在 netlify.toml 或 UI 中覆盖（项目配置 > 构建与部署 > 持续部署 > 构建设置）。

SSR / 适配器设置

Astro

npx astro add netlify 会安装适配器并修改 astro.config.mjs。SSR 和开箱即用的 <Image /> 图片 CDN 均需要适配器。SSR → Netlify Functions；中间件 → Edge Functions。仅当不需要服务器功能和图片 CDN 时，才能不使用适配器进行部署。自 5.15.0 起支持版本偏移保护。

Next.js（仅限 13.5+）

通过 OpenNext 适配器（@netlify/plugin-nextjs）实现零配置。请勿固定版本 — Netlify 会在每次构建时自动更新。旧版适配器仅作历史参考，绝不推荐使用。 适配器提供：用于 SSR/ISR/PPR/路由处理程序/Server Actions 的无服务器函数；用于中间件的 Edge Function；完整路由 + 数据缓存；搭配 next/image 使用的图片 CDN。 版本偏移保护需选择启用：设置 NETLIFY_NEXT_SKEW_PROTECTION=true，然后重新部署。不自动支持客户端 fetch — 需直接调用并使用 x-deployment-id: process.env.NEXT_DEPLOYMENT_ID。详情见 references/nextjs.md。

SvelteKit

npm install -D @sveltejs/adapter-netlify

import adapter from '@sveltejs/adapter-netlify';
export default { kit: { adapter: adapter() } };

将 @sveltejs/adapter-auto 替换为特定的导入。SSR 路由 → 一个 render 函数。

• split: true → 每个路由一个函数。与 Edge Functions 不兼容（edge: false 或省略）。
• edge: true → 在 Deno Edge Function 中执行 SSR；不能与 split 同时使用。
• 不支持在 netlify.toml 中配置重定向 — 请使用 _redirects。
• 在本地使用 netlify dev 时，SvelteKit 的 Edge Functions 无法运行。

React Router（7+）

新建项目：npx create-react-router@latest --template netlify/react-router-template。已有项目：

npm install @netlify/vite-plugin-react-router

将 netlifyReactRouter() 添加到 Vite 插件中。默认目标 = Serverless Functions。 Edge（Deno）：需要插件 v2.1.1+，设置 edge: true，并且必须创建 app/entry.server.tsx：

export { default } from 'virtual:netlify-server-entry'

排除你自己的函数路径：netlifyReactRouter({ edge: true, excludedPaths: ['/api/*'] })。 **切回 Serverless：**移除 edge: true，并删除 app/entry.server.tsx。 中间件（React Router v7.9.0+，插件 v2.0.0+）：通过 future.v8_middleware 选择启用；从 @netlify/vite-plugin-react-router/serverless 导入 netlifyRouterContext（若设置了 edge: true，则从 /edge 导入）；通过 context.get(netlifyRouterContext) 访问。

Remix

新建项目：npx create-remix@latest --template netlify/remix-template（CLI 会提示选择 Functions 或 Edge Functions）。手动配置（需要 Remix Vite）：

npm install --save-dev @netlify/remix-adapter

将来自 @netlify/remix-adapter/plugin 的 netlifyPlugin() 添加到 Vite 插件中。

Nuxt

通过 Nitro 实现 SSR，Nuxt 3 会自动配置。通过 @netlify/nuxt 保持本地环境一致（npx nuxi module add @netlify/nuxt）。

• 在 Edge Functions 上运行 SSR 需要使用不同的 Nitro 部署预设（不会自动检测）。
• pnpm + Nuxt 3：设置 PNPM_FLAGS=--shamefully-hoist。
• nuxt/image 会自动使用 Netlify 图片 CDN；在 nuxt.config.ts 中设置远程域名。

SolidStart

SolidStart 2 基于 Vite 构建 — 没有 SolidStart 专用适配器。安装 @netlify/vite-plugin：

import netlify from "@netlify/vite-plugin";
import { solidStart } from "@solidjs/start/config";
import { defineConfig } from "vite";
export default defineConfig({
  plugins: [solidStart(), netlify({ build: { enabled: true } })],
});

发布 dist/client。SSR 路由、服务器函数、中间件 → Netlify Functions，无需额外配置。 **Nitro 替代方案：**添加 nitro()，使用普通的 netlify()（不设置 build.enabled），发布 dist。 SolidStart 1：Nitro 会自动配置；也可以选择在 app.config.ts 中设置 preset: "netlify"；使用 vinxi build / dist。

TanStack Start

React（以及 Solid.js）全栈框架；SSR/服务器路由/服务器函数/中间件 → 无服务器函数。

npm install -D @netlify/vite-plugin-tanstack-start

将 netlify() 与 tanstackStart() 一起添加到 Vite 插件中；vite build / dist/client（1.132.0+）。使用 Netlify CLI 部署需要 netlify-cli 17.31+。旧版本请参阅 references/tanstack.md。

Gatsby

• **5.12.0+（适配器）：**自动检测并安装 gatsby-adapter-netlify（零配置）。生成 SSR、DSG 函数。无需 Essential Gatsby 插件。
• **5.11.0 或更早版本（Essential Gatsby 插件）：**自动安装 @netlify/plugin-gatsby；还需手动安装 gatsby-plugin-netlify（SSR、Gatsby 重定向和资源缓存必需）。生成 __api、__ssr、__dsg、__ipx。使用 NETLIFY_SKIP_GATSBY_FUNCTIONS（全部）/ NETLIFY_SKIP_API_FUNCTION / NETLIFY_SKIP_SSR_FUNCTION / NETLIFY_SKIP_DSG_FUNCTION 跳过。
• Gatsby 5 需要 Node 18。
• 大型站点：设置 GATSBY_EXCLUDE_DATASTORE_FROM_BUNDLE，从 CDN 加载 datastore（避免超出函数部署大小上限；首次加载 SSR/DSG 的速度会变慢）。
• 图像 CDN：设置 NETLIFY_IMAGE_CDN=true（Contentful/Drupal/WordPress source 插件）。在使用适配器的 5.12.x 版本中不受支持——请升级到 5.13.0+。
• StaticImage 和 gatsby-transformer-sharp 不适用于 SSR/DSG——请将图像托管在 CDN 上。

Angular

通过 Edge Function 自动配置 SSR。建议的开发命令：ng serve / 4200。

• SSR 页面不受 _redirects 或 netlify.toml 重定向规则约束——SSR 使用在重定向之前运行的 Edge Functions。请使用 Angular 内置的重定向功能。
• 在 SSR 中通过 netlify.request / netlify.context 提供程序（来自 @netlify/edge-functions）访问 Request/Context；客户端和预渲染期间不可用。使用 netlify serve 在本地测试。
• NgOptimizedImage 会自动使用 Image CDN；在 netlify.toml 的 [images] 下设置 remote_images（正则表达式数组）。

Express

Node 18.14.0+。通过 serverless-http 部署为 Netlify Function：

npm i express serverless-http @netlify/functions @types/express

// netlify/functions/api.ts
import express, { Router } from "express";
import serverless from "serverless-http";
const api = express();
const router = Router();
router.get("/hello", (req, res) => res.send("Hello World!"));
api.use("/api/", router);
export const handler = serverless(api);

[functions]
  external_node_modules = ["express"]
  node_bundler = "esbuild"
[[redirects]]
  force = true
  from = "/api/*"
  status = 200
  to = "/.netlify/functions/api/:splat"

没有前端：设置一个占位构建命令（例如 echo Building Functions）。所有 Function 限制均适用；不建议用作后台函数或定时函数。

Hydrogen

基于 React Router 7 的 Shopify 技术栈。**仅在 Netlify Edge Functions 上支持 SSR——Netlify Functions 不受官方支持。**Node 24+。使用入门模板：

npm create @shopify/hydrogen@latest -- --template https://github.com/netlify/hydrogen-template
cp .env.example .env && npm run dev

静态站点注意事项

Hugo

在 [build.environment] 中设置 HUGO_VERSION（0.19 之后的任意版本）——版本缺失或不匹配会导致 exit code: 255。将主题安装为 git submodules（git submodule add ...），而不是使用 git clone。

Eleventy

eleventy / _site。构建插件需要编辑 .gitignore：将 node_modules 改为 **/node_modules/**——否则 Netlify 插件和 Eleventy 会在 .netlify/plugins/node_modules/ 发生冲突，导致构建报错。

Vite 元框架支持矩阵

Astro（5.12+ 自动支持）、Nuxt（通过 @netlify/nuxt）、TanStack Start（通过 @netlify/vite-plugin-tanstack-start）、React Router、SolidStart——均为完整支持。SvelteKit——实验性支持。

通过 CLI 部署（Express、Nuxt、React、Vite）

npm install netlify-cli -g
netlify init

按照提示创建/关联站点并设置构建配置。

Netlify 规范（框架）

这些是组织约定，不是文档事实——由 ctx-gen 合并到渲染后的技能中，绝不会自动生成。由技能维护者负责。

1. 各框架的深入指南位于此技能中：references/astro.md、 references/nextjs.md、references/nuxt.md、references/sveltekit.md、 references/tanstack.md、references/vite.md——处理框架特定工作前，先查阅对应指南， 不要自行发挥。
2. Next.js：仅限现代运行时（v5、Next ≥13.5）——将旧版适配器视为只读历史记录，绝不要推荐。
3. 采用 SSR 适配器时，移除所有 SPA 全匹配规则（/* → /index.html 200）——用户重定向的优先级高于适配器生成的路由，因此遗留的全匹配规则会悄无声息地为 SSR 页面和 API 路由提供静态 index.html。
4. 任何环境变量变更（客户端或服务端）都需要重新部署。值会在构建时注入；在 UI/CLI 中编辑环境变量，不会让变更应用到线上站点或已部署的函数，必须运行新的构建。
5. netlify dev 同时配置自定义 command 和 targetPort 时，需要在 [dev] 块中设置 framework = "#custom"——否则检测器会运行，自定义命令会被悄无声息地忽略。
6. 绝不要将客户端前缀（VITE_、NEXT_PUBLIC_、PUBLIC_、 NUXT_PUBLIC_、REACT_APP_、GATSBY_、VUE_APP_）用于机密——带客户端前缀的变量会被内联到浏览器包中。
7. Next.js 偏斜保护取决于版本：低于 Next 14.1.4 时，仅设置 NETLIFY_NEXT_SKEW_PROTECTION 环境变量并不足够——还必须在 next.config.js 中配置 experimental.useDeploymentId（如果使用了服务器操作，还要配置 useDeploymentIdServerActions）。务必询问或注明版本条件；绝不要将环境变量说成完整配置。
8. 默认情况下，Next.js 偏斜保护不涵盖客户端 fetch 调用。请同时给出两种选项。Next.js 15.4+ 提供实验性的 useSkewCookie 标志，可通过 Cookie 携带部署标识符，使其随客户端 fetch 调用一并发送；Netlify 支持此功能，但应说明它尚未达到生产就绪状态，而且在 Cookie 过期前，访客会一直停留在旧部署版本上。另一种适用于任何版本的选项，是在每次调用时使用 process.env.NEXT_DEPLOYMENT_ID 添加 x-deployment-id。