Question

此适配器可以部署你的 hybrid 或 server 渲染站点 到 Netlify。

如果你正在使用 Astro 作为静态站点生成器，则不需要适配器。

在我们的 Netlify 部署指南 中学习如何部署你的 Astro 网站。

为什么是 Astro Netlify

Netlify 是一个部署平台，允许你通过直接连接 GitHub 仓库来托管你的网站。这个适配器增强了 Astro 的构建流程，为通过 Netlify 部署项目做好准备。

安装

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

在 Astro 项目中使用以下 asrto add 命令添加 Netlify 适配器，以启用 SSR。这将安装 @astrojs/netlify 并一步到位地对你的 astro.config.mjs 文件进行相应的更改。

• npm
• pnpm
• Yarn

npm run astro add netlify

pnpm astro add netlify

yarn astro add netlify

手动安装

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

• npm
• pnpm
• Yarn

npm install @astrojs/netlify

pnpm add @astrojs/netlify

yarn add @astrojs/netlify

然后，将适配器和你所需的按需渲染模式添加到你的 astro.config.* 文件中：

astro.config.mjs

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


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

用法

阅读完整的部署指南

按照指南 在本地构建你的站点。构建完成后，你将会有一个包含 Netlify Functions 的 .netlify/ 文件夹，其中包含 .netlify/functions-internal/ 文件夹中的函数和 .netlify/edge-functions/ 文件夹中的 Netlify Edge Functions。

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

netlify deploy

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

从你的站点访问 edge 上下文

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

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

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


<h1>你好，来自{city}的友好访客！</h1>

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

src/env.d.ts

/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />


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


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

这不适用于预渲染的页面。

在 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({
  // ...
  output: 'server',
  adapter: netlify({    edgeMiddleware: true,
  }),
});

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

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

Netlify 图片 CDN 支持

这个适配器默认使用 Netlify 图片 CDN 来实时转换图片，因而不会影响构建时间。 它背后是使用 Astro 图片服务 实现的。

如果你想退出 Netlify 的图片 CDN 远程图片优化，可以使用 imageCDN 选项：

astro.config.mjs

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


export default defineConfig({
  // ...
  output: 'server',
  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({
    // ...
    output: 'server',
    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/static';


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

一旦你运行了 astro build，就会有一个 dist/_redirects 文件。Netlify 将使用它来正确地路由生产环境中的页面。

注意

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

缓存页面

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

astro.config.mjs

export default defineConfig({
  // ...
  output: 'server',
  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

示例

• Astro Netlify Edge Starter 提供了一个示例以及 README 中的指南。
• 浏览 GitHub 上的 Astro Netlify 项目 查看更多示例！

更多集成

UI 框架

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR 适配器

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

其他集成

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind

Recipes