@astrojs/ netlify

v4.1.0 GitHub npm Changelog

此适配器可以部署你的 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 run astro add netlify

pnpm astro add netlify

yarn astro add netlify

手动安装

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

npm install @astrojs/netlify

pnpm add @astrojs/netlify

yarn add @astrojs/netlify

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

 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 来获得正确的类型：

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

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

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

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

在 Edge Functions 中运行 Astro 中间件

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

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

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

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

配置 edgeMiddleware: true 将会将你的中间件部署为 Edge Function，并在所有路由上运行它——包括预渲染的页面。但是，中间件中指定的 locals 不会对任何预渲染的页面可用，因为它们已经在构建时完全渲染了。

Netlify 图片 CDN 支持

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

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

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

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

静态站点和重定向

对于静态站点，你通常不需要适配器。但是，如果你在 Astro 配置中使用了 redirects 配置，Netlify 适配器可以将其转换为正确的 _redirects 格式。

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 将使用它来正确地路由生产环境中的页面。

缓存页面

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

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

这可以通过向你的响应添加缓存头来根据每个页面进行更改：

---
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>