@astrojs/ netlify

v4.0.1 GitHub npm Changelog

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

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

为什么是 Astro Netlify

如果你正在使用 Astro 作为静态站点生成器——也就是它的开箱即用的行为——你不需要一个适配器。

如果你希望使用按需渲染，也称作服务器端渲染（SSR），Astro 需要一个与你的部署运行时相匹配的适配器。

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

安装

使用以下 astro add 命令添加 Netlify 适配器。这将在一步中安装适配器并对 astro.config.mjs 文件进行适当的更改。

# Using NPM
npx astro add netlify
# Using Yarn
yarn astro add netlify
# Using PNPM
pnpm astro add netlify

手动添加依赖

如果你更喜欢手动安装适配器，请完成以下两个步骤：

安装 Netlify 适配器到你的项目依赖中，使用你喜欢的包管理器。如果你使用 npm 或者不确定，请在终端中运行：

  npm install @astrojs/netlify

添加两行内容到你的 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 来获得正确的类型：

/// <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 图片服务实现的。

静态站点和重定向

对于静态站点，你通常不需要适配器。但是，如果你在 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>