@astrojs/ netlify

此适配器允许 Astro 将你的按需渲染的路由和功能部署到 Netlify，包括 server islands、actions 和 sessions。

如果你将 Astro 用作静态站点构建器，则仅当使用需要服务器的附加 Netlify 服务（例如 Netlify Image CDN）时才需要此适配器。否则，你不需要适配器来部署静态站点。

在我们的Netlify 部署指南中了解如何部署你的 Astro 站点。

为何选择 Astro Netlify

Netlify 是一个部署平台，允许你通过直接连接到你的 GitHub 仓库来托管你的站点。此适配器增强了 Astro 的构建过程，以便为通过 Netlify 进行部署做准备。

安装

Astro 包含一个 astro add 命令来自动设置官方集成。如果你愿意，也可以手动安装集成。

使用 astro add 命令添加 Netlify 适配器，以在你的 Astro 项目中启用按需渲染。这将一步完成 @astrojs/netlify 的安装，并对你的 astro.config.mjs 文件进行适当的更改。

npm

npx astro add netlify

pnpm

pnpm astro add netlify

Yarn

yarn astro add netlify

现在，你可以为每个页面启用按需渲染，或将你的构建输出配置设置为 output: 'server' 以默认对所有页面进行服务器端渲染。

手动安装

首先，使用你偏好的包管理器将 Netlify 适配器安装到你项目的依赖项中

npm

npm install @astrojs/netlify

pnpm

pnpm add @astrojs/netlify

Yarn

yarn add @astrojs/netlify

然后，将适配器添加到你的 astro.config.* 文件中

astro.config.mjs

 import { defineConfig } from 'astro/config';
 import netlify from '@astrojs/netlify';

 export default defineConfig({
    // ...
    adapter: netlify(),
 });

用法

在此处阅读完整的部署指南。

按照说明在本地构建你的站点。构建后，你将得到一个 .netlify/ 文件夹，其中包含 .netlify/functions-internal/ 文件夹中的 Netlify Functions 和 .netlify/edge-functions/ 文件夹中的 Netlify Edge Functions。

要部署你的站点，请安装 Netlify CLI 并运行

netlify deploy

关于 Astro 的 Netlify 博客文章和 Netlify 文档 提供了有关如何使用此集成部署到 Netlify 的更多信息。

在 Netlify Edge Functions 上运行 Astro 中间件

任何 Astro 中间件都会在构建时应用于预渲染页面，并在运行时应用于按需渲染页面。

要为预渲染页面实现重定向、访问控制或自定义响应头，请通过启用edgeMiddleware 选项在 Netlify Edge Functions 上运行你的中间件

astro.config.mjs

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    edgeMiddleware: true,
  }),
});

当 edgeMiddleware 启用时，一个边缘函数将为所有请求执行你的中间件代码，包括静态资源、预渲染页面和按需渲染页面。

对于按需渲染的页面，context.locals 对象将使用 JSON 序列化，并通过请求头发送给执行渲染的无服务器函数。作为一项安全措施，无服务器函数将拒绝处理非来自生成的边缘函数的请求，并返回 403 Forbidden 响应。

从你的网站访问边缘上下文

Netlify Edge Functions 提供一个上下文对象，其中包含有关请求的元数据，例如用户的 IP、地理位置数据和 cookie。

这可以通过 Astro.locals.netlify.context 对象来访问

---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---

<h1>Hello there, friendly visitor from {city}!</h1>

如果你正在使用 TypeScript，你可以通过更新 src/env.d.ts 文件来使用 NetlifyLocals 以获得正确的类型定义

src/env.d.ts

type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals

declare namespace App {
  interface Locals extends NetlifyLocals {
    // ...
  }
}

这在预渲染页面上不可用。

Netlify Image CDN 支持

默认情况下，此适配器使用 Netlify Image CDN 来即时转换图像，而不会影响构建时间。它在底层是使用Astro 图像服务实现的。

要选择不使用 Netlify 的 Image CDN 远程图像优化，请使用 imageCDN 选项

astro.config.mjs

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    imageCDN: false,
  }),
});

如果你使用的图片托管在其他域名上，你必须使用 image.domains 或 image.remotePatterns 配置选项来授权该域名或 URL 模式

astro.config.mjs

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
    // ...
    adapter: netlify(),
    image: {
      domains: ['example.com'],
    },
});

更多信息，请参阅授权远程图像指南。对于托管在与你的站点相同域名下的图像，则不需要此项配置。

使用 Netlify 适配器的静态站点

对于托管在 Netlify 上的静态站点（output: 'static'），你通常不需要适配器。但是，某些部署功能只能通过适配器获得。

静态站点需要安装此适配器才能使用和配置 Netlify 的图像服务。

如果你在 Astro 配置中使用了 redirects 配置，Netlify 适配器可以将其转换为正确的 _redirects 格式。

astro.config.mjs

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  },
});

一旦你运行 astro build，将会生成一个 dist/_redirects 文件。Netlify 将使用该文件在生产环境中正确地路由页面。

注意

你仍然可以在 public/_redirects 文件中包含手动重定向。你在重定向配置中指定的任何重定向都会附加到你自己的文件末尾。

会话

Astro 会话 API 允许你在请求之间轻松存储用户数据。这可以用于用户数据和偏好设置、购物车和身份验证凭据等。与 cookie 存储不同，数据没有大小限制，并且可以在不同设备上恢复。

使用 Netlify 适配器时，Astro 会自动为会话存储配置 Netlify Blobs。如果你希望使用不同的会话存储驱动程序，可以在 Astro 配置中指定。更多详细信息，请参阅session 配置参考。

缓存页面

没有任何动态内容的按需渲染页面可以被缓存，以提高性能和降低资源使用。在适配器中启用 cacheOnDemandPages 选项将缓存所有服务器渲染的页面，最长可达一年

astro.config.mjs

export default defineConfig({
  // ...
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});

这可以通过向你的响应中添加缓存头来逐页更改

pages/index.astro

---
import Layout from '../components/Layout.astro';

Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');
---

<Layout title="Astro on Netlify">
  {new Date()}
</Layout>

通过细粒度缓存控制，Netlify 支持标准的缓存头，如 CDN-Cache-Control 或 Vary。请参阅文档以了解如何实现例如生存时间（TTL）或后台异步验证（SWR）缓存：https://docs.netlify.com/platform/caching

在 Netlify Functions 中包含或排除文件

当将具有按需渲染的 Astro 站点部署到 Netlify 时，生成的函数会自动追踪并包含服务器依赖项。但是，你可能需要自定义哪些文件包含在你的 Netlify Functions 中。

includeFiles

类型： string[]
默认值： []

添加于： astro@5.3.0

includeFiles 属性允许你明确指定应与你的函数捆绑的额外文件。这对于那些未被自动检测为依赖项的文件非常有用，例如

• 使用 fs 操作加载的数据文件
• 配置文件
• 模板文件

提供一个要包含的额外文件数组，文件路径相对于你的项目 root。绝对路径可能无法按预期工作。

astro.config.mjs

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    includeFiles: ['./my-data.json'], // relative to `root`
  }),
});

excludeFiles

类型： string[]
默认值： []

添加于： astro@5.3.0

你可以使用 excludeFiles 属性来防止某些本应被捆绑的文件被包含进来。这对于以下情况很有帮助

• 减小捆绑包大小
• 排除大型二进制文件
• 防止不想要的文件被部署

提供一个要排除的特定文件数组，文件路径相对于你的项目 root。绝对路径可能无法按预期工作。

astro.config.mjs

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    excludeFiles: ['./src/some_big_file.jpg'], // relative to `root`
  }),
});

使用 glob 模式

includeFiles 和 excludeFiles 都支持glob 模式来匹配多个文件

astro.config.mjs

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  adapter: netlify({
    includeFiles: [
      './data/**/*.json'
    ],
    excludeFiles: [
      './node_modules/package/**/*',
      './src/**/*.test.js'
    ]
  }),
});

本地开发功能

运行 astro dev 时，适配器会启用多个 Netlify 平台功能，以确保环境尽可能与生产环境匹配。这些功能包括

• 一个本地的 Netlify Image CDN 服务器。默认情况下，它用于图像。
• 一个本地的 Netlify Blobs 服务器。默认情况下，它用于会话
• 来自你的 Netlify 配置的重定向、重写和请求头
• 在按需页面中访问 Netlify Edge Context
• 来自你的 Netlify 站点的环境变量

当你的本地站点使用 netlify link 链接到 Netlify 站点时，这些功能效果最佳。

你可以使用适配器配置中的 devFeatures 选项来启用或禁用其中一些功能。默认情况下，除了环境变量外，所有功能都已启用。

devFeatures

类型： boolean | object
默认值： { images: true, environmentVariables: false }

添加于： @astrojs/netlify@6.5.1 新

devFeatures 选项可以是一个布尔值（用于启用或禁用所有功能），也可以是一个对象（用于启用特定功能）。

astro.config.mjs

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    devFeatures: {
      // Enable Netlify Image CDN support in dev. Defaults to true.
      images: false,
      // Inject Netlify environment variables in dev. Defaults to false.
      environmentVariables: true,
    },
  }),
});

devFeatures.images

类型： boolean
默认值： true

添加于： @astrojs/netlify@6.5.1 新

在开发中启用对本地 Netlify Image CDN 的支持。

这会使用 Netlify Image CDN 的本地版本，而不是默认的 Astro 图像服务。

devFeatures.environmentVariables

类型： boolean
默认值： false

添加于： @astrojs/netlify@6.5.1 新

将来自你的 Netlify 站点的环境变量注入到开发环境中。

这允许你在开发中使用与生产环境相同的值。有关更多信息，包括如何为不同环境使用不同变量，请参阅Netlify 关于环境变量的文档。

实验性功能

以下功能也可用，但在未来的更新中可能会有破坏性更改。如果你在项目中使用这些功能，请仔细关注 @astrojs/netlify CHANGELOG 以获取更新。

experimentalStaticHeaders

类型： boolean
默认值： false

添加于： @astrojs/netlify@6.4.0

允许在 Netlify 的配置中为预渲染页面指定自定义请求头。

如果启用，当 Astro 功能（例如内容安全策略）提供静态请求头时，适配器会将其保存在框架 API 配置文件中。

例如，当启用实验性内容安全策略时，可以使用 experimentalStaticHeaders 将 CSP headers 添加到你的 Netlify 配置中，而不是创建一个 <meta> 元素

astro.config.mjs

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  experimental: {
    csp: true
  },
  adapter: netlify({
    experimentalStaticHeaders: true
  })
});

示例

• Astro Netlify Edge Starter 在 README 中提供了一个示例和指南。

• 在 GitHub 上浏览 Astro Netlify 项目以获取更多示例！

更多集成

前端框架

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

适配器

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

其他集成

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap