Skip to content

@astrojs/ netlify

v6.0.1 GitHub npm 更新日志

此适配器允许 Astro 将你的 按需渲染路由 部署到 Netlify。

¥This adapter allows Astro to deploy your on-demand rendered routes to Netlify.

如果你使用 Astro 作为静态站点构建器，则不需要适配器。

¥If you’re using Astro as a static site builder, you don’t need an adapter.

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

¥Learn how to deploy your Astro site in our Netlify deployment guide.

为什么选择 Astro Netlify

标题部分 为什么选择 Astro Netlify

¥Why Astro Netlify

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

¥Netlify is a deployment platform that allows you to host your site by connecting directly to your GitHub repository. This adapter enhances the Astro build process to prepare your project for deployment through Netlify.

安装

标题部分 安装

¥Installation

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

¥Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

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

¥Add the Netlify adapter to enable SSR in your Astro project with the astro add command. This will install @astrojs/netlify and make the appropriate changes to your astro.config.mjs file in one step.

终端窗口
npx astro add netlify

手动安装

标题部分 手动安装

¥Manual Install

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

¥First, install the Netlify adapter to your project’s dependencies using your preferred package manager:

终端窗口
npm install @astrojs/netlify

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

¥Then, add the adapter and your desired on-demand rendering mode to your astro.config.* file:

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


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

用法

标题部分 用法

¥Usage

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

¥Read the full deployment guide here.

按照 在本地构建你的网站 的说明进行操作。构建后，你将拥有一个 .netlify/ 文件夹，其中包含 .netlify/functions-internal/ 文件夹中的 Netlify 函数 和 .netlify/edge-functions/ 文件夹中的 Netlify Edge 函数。

¥Follow the instructions to build your site locally. After building, you will have a .netlify/ folder containing both Netlify Functions in the .netlify/functions-internal/ folder and Netlify Edge Functions in the.netlify/edge-functions/ folder.

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

¥To deploy your site, install the Netlify CLI and run:

终端窗口
netlify deploy

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

¥The Netlify Blog post on Astro and the Netlify Docs provide more information on how to use this integration to deploy to Netlify.

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

标题部分 从你的站点访问边缘上下文

¥Accessing edge context from your site

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

¥Netlify Edge Functions provide a context object that includes metadata about the request such as a user’s IP, geolocation data, and cookies.

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

¥This can be accessed through the Astro.locals.netlify.context object:

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


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

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

¥If you’re using TypeScript, you can get proper typings by updating src/env.d.ts to use NetlifyLocals:

src/env.d.ts
type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals


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

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

¥This is not available on prerendered pages.

在 Netlify Edge Functions 上运行 Astro 中间件

标题部分 在 Netlify Edge Functions 上运行 Astro 中间件

¥Running Astro middleware on Netlify Edge Functions

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

¥Any Astro middleware is applied to pre-rendered pages at build-time, and to on-demand-rendered pages at runtime.

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

¥To implement redirects, access control or custom response headers for pre-rendered pages, run your middleware on Netlify Edge Functions by enabling the edgeMiddleware option:

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


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

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

¥When edgeMiddleware is enabled, an edge function will execute your middleware code for all requests including static assets, prerendered pages, and on-demand rendered pages.

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

¥For on-demand rendered pages, the context.locals object is serialized using JSON and sent in a header for the serverless function, which performs the rendering. As a security measure, the serverless function will refuse to serve requests with a 403 Forbidden response unless they come from the generated edge function.

Netlify Image CDN 支持

标题部分 Netlify Image CDN 支持

¥Netlify Image CDN support

此适配器默认使用 Netlify 图片 CDN 即时转换图片，而不会影响构建时间。它是使用 Astro 图​​像服务 在后台实现的。

¥This adapter by default uses the Netlify Image CDN to transform images on-the-fly without impacting build times. It’s implemented using an Astro Image Service under the hood.

要退出 Netlify 的 Image CDN 远程图片优化，请使用 imageCDN 选项：

¥To opt out of Netlify’s Image CDN remote image optimization, use the imageCDN option:

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 模式：

¥If you are using images hosted on another domain, you must authorize the domain or URL patterns using the image.domains or image.remotePatterns configuration options:

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


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

有关更多信息，请参阅 授权远程图片的指南。对于托管在与你的网站相同的域上的图片，这不是必需的。

¥For more information, see the guide to authorizing remote images. This is not required for images hosted on the same domain as your site.

使用 Netlify 适配器的静态站点

标题部分 使用 Netlify 适配器的静态站点

¥Static sites with the Netlify Adapter

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

¥For static sites (output: 'static') hosted on Netlify, you usually don’t need an adapter. However, some deployment features are only available through an adapter.

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

¥Static sites will need to install this adapter to use and configure Netlify’s image service.

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

¥If you use redirects configuration in your Astro config, the Netlify adapter can be used to translate this to the proper _redirects format.

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

¥Once you run astro build there will be a dist/_redirects file. Netlify will use that to properly route pages in production.

缓存页面

标题部分 缓存页面

¥Caching Pages

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

¥On-demand rendered pages without any dynamic content can be cached to improve performance and lower resource usage. Enabling the cacheOnDemandPages option in the adapter will cache all server-rendered pages for up to one year:

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

可通过向响应添加缓存标头来逐页更改：

¥This can be changed on a per-page basis by adding caching headers to your response:

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

¥With fine-grained cache control, Netlify supports standard caching headers like CDN-Cache-Control or Vary. Refer to the docs to learn about implementing e.g. time to live (TTL) or stale while revalidate (SWR) caching: https://docs.netlify.com/platform/caching

示例

标题部分 示例

¥Examples

更多集成

前端框架

SSR 适配器

其他集成

Astro 中文网 - 粤ICP备13048890号