跳转到内容

@astrojs/ netlify

此适配器可以部署你的 hybridserver 渲染站点Netlify

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

为什么是 Astro Netlify

段落标题 为什么是 Astro Netlify

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

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

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

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

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

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

  1. 安装 Netlify 适配器到你的项目依赖中,使用你喜欢的包管理器。如果你使用 npm 或者不确定,请在终端中运行:
Terminal window
npm install @astrojs/netlify
  1. 添加两行内容到你的 astro.config.mjs 项目配置文件中。
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 并运行:

Terminal window
netlify deploy

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

从你的站点访问 edge 上下文

段落标题 从你的站点访问 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 {
...
}
}

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

在 Edge Functions 中运行 Astro 中间件

段落标题 在 Edge Functions 中运行 Astro 中间件

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

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

astro.config.mjs
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 来实时转换图片,而不会影响构建时间。 它背后是使用 Astro 图片服务 实现的。

对于静态站点,你通常不需要适配器。但是,如果你在 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 将使用它来正确地路由生产环境中的页面。

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

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

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

src/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-ControlVary。 请参阅文档,了解如何实现例如 TTL 或 SWR 缓存:https://docs.netlify.com/platform/caching

寻求帮助,请查看 Discord 上的 #support 频道。我们友好的支持小组成员在这里帮助你!

你还可以查看我们的 Astro 集成文档 了解更多关于集成的信息。

这个项目由 Astro 核心团队维护。欢迎提交 issue 或 PR!

查看 CHANGELOG.md,了解本集成的更改历史。

More integrations

UI 框架

SSR 适配器

其他