@astrojs/ vercel

此适配器允许你将 Astro 的按需渲染路由和功能部署到 Vercel，包括服务器岛屿、操作和会话。

如果你将 Astro 用作静态网站生成器，那么只有在你使用额外的 Vercel 服务（例如 Vercel Web Analytics、Vercel Image Optimization）时才需要此适配器。否则，你不需要适配器来部署你的静态网站。

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

为何选择 Astro Vercel？

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

安装

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

使用以下 astro add 命令添加 Vercel 适配器，以在你的 Astro 项目中启用按需渲染。这将一步完成 @astrojs/vercel 的安装并对你的 astro.config.mjs 文件进行适当的更改。

npm

npx astro add vercel

pnpm

pnpm astro add vercel

Yarn

yarn astro add vercel

现在，你可以为每个页面启用按需渲染，或者将你的构建输出配置设置为 output: 'server' 来默认对所有页面进行服务器端渲染。

手动安装

首先，使用你偏好的包管理器将 @astrojs/vercel 适配器添加到你项目的依赖项中

npm

npm install @astrojs/vercel

pnpm

pnpm add @astrojs/vercel

Yarn

yarn add @astrojs/vercel

然后，将适配器添加到你的 astro.config.* 文件中

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: vercel(),
});

用法

了解更多关于将你的项目部署到 Vercel 的信息。

你可以通过 CLI（vercel deploy）部署，或在 Vercel Dashboard 中连接你的新仓库。或者，你可以在本地创建一个生产构建

astro build
vercel deploy --prebuilt

配置

要配置此适配器，请在 astro.config.mjs 中将一个对象传递给 vercel() 函数调用

webAnalytics

类型： VercelWebAnalyticsConfig
适用于： 无服务器、静态

添加于： @astrojs/vercel@3.8.0

对于 @vercel/analytics@1.3.x 或更早版本，你可以在你的 Astro 配置中设置 webAnalytics: { enabled: true }，以将 Vercel 的跟踪脚本注入到你的所有页面中。

对于 @vercel/analytics@1.4.0 及更高版本，请改用 Vercel 的 Analytics 组件来启用 Vercel Web Analytics。

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: vercel({
    webAnalytics: {
      enabled: true,
    },
  }),
});

imagesConfig

类型： VercelImageConfig
适用于： 无服务器、静态

添加于： @astrojs/vercel@3.3.0

Vercel 图像优化 API 的配置选项。有关支持的参数的完整列表，请参阅 Vercel 的图像配置文档。

domains 和 remotePatterns 属性将使用 Astro 相应的 image 配置自动填充。

astro.config.mjs

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

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imagesConfig: {
      sizes: [320, 640, 1280],
    },
  }),
});

imageService

类型： boolean
适用于： 无服务器、静态

添加于： @astrojs/vercel@3.3.0

启用后，一个由 Vercel 图像优化 API 驱动的图像服务将在生产环境中自动配置和使用。在开发环境中，将改用由 devImageService 指定的图像服务。

astro.config.mjs

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

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imageService: true,
  }),
});

src/pages/index.astro

---
import { Image } from 'astro:assets';
import astroLogo from '../assets/logo.png';
---

<!-- This component -->
<Image src={astroLogo} alt="My super logo!" />

<!-- will become the following HTML -->
<img
  src="/_vercel/image?url=_astro/logo.hash.png&w=...&q=..."
  alt="My super logo!"
  loading="lazy"
  decoding="async"
  width="..."
  height="..."
/>

devImageService

类型： 'sharp' | string
适用于： 无服务器、静态

添加于： @astrojs/vercel@3.8.0

默认值： sharp

当 imageService 启用时，此选项允许你配置在开发环境中使用哪个图像服务。如果你的开发机器无法安装 Sharp 的依赖项，这会很有用，但使用像 Squoosh 这样的其他图像服务可以让你在开发环境中预览图像。构建不受影响，将始终使用 Vercel 的图像优化。

它也可以设置为任意值，以便使用自定义图像服务而不是 Astro 的内置服务。

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: vercel({
    imageService: true,
    devImageService: 'sharp',
  }),
});

isr

类型： boolean | VercelISRConfig
适用于： 无服务器

添加于： @astrojs/vercel@7.2.0

默认值： false

允许你的项目部署为 ISR（增量静态再生）函数，该函数在首次请求后，会以与预渲染页面相同的方式缓存按需渲染的页面。

要启用此功能，请在 astro.config.mjs 的 Vercel 适配器配置中将 isr 设置为 true

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: vercel({
    isr: true,
  }),
});

请注意，ISR 函数请求不包含搜索参数，这与静态模式下的请求类似。

ISR 缓存失效

默认情况下，ISR 函数会在部署期间进行缓存。你可以通过设置过期时间或将特定路由完全从缓存中排除来进一步控制缓存。

基于时间的失效

你可以通过配置以秒为单位的 expiration 值来更改路由的缓存时长

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: vercel({
    isr: {
      // caches all pages on first request and saves for 1 day
      expiration: 60 * 60 * 24,
    },
  }),
});

从缓存中排除路径

要实现 Vercel 的草稿模式或按需增量静态再生 (ISR)，你可以创建一个绕过令牌，并将其与要从缓存中排除的任何路由一起提供给 isr 配置

astro.config.mjs

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

export default defineConfig({
    adapter: vercel({
        isr: {
            // A secret random string that you create.
            bypassToken: "005556d774a8",
            // Paths that will always be served fresh.
            exclude: [
              '/preview',
              '/auth/[page]',
              /^\/api\/.+/ // Regular expressions supported since @astrojs/vercel@v8.1.0
            ]
        }
    })
})

includeFiles

类型： string[]
适用于： 无服务器

使用此属性强制将文件与你的函数打包。当你发现有文件丢失时，这会很有帮助。

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: vercel({
    includeFiles: ['./my-data.json'],
  }),
});

excludeFiles

类型： string[]
适用于： 无服务器

使用此属性可以从打包过程中排除那些本应被包含的文件。

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: vercel({
    excludeFiles: ['./src/some_big_file.jpg'],
  }),
});

maxDuration

类型： number
适用于： 无服务器

使用此属性可延长或限制无服务器函数在超时前可以运行的最长持续时间（以秒为单位）。有关你账户计划的默认和最大限制，请参阅 Vercel 文档。

astro.config.mjs

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

export default defineConfig({
// ...
  adapter: vercel({
    maxDuration: 60
  }),
});

skewProtection

类型： boolean
适用于： 无服务器

添加于： @astrojs/vercel@7.6.0

使用此属性以启用 Vercel Skew protection（适用于 Vercel Pro 和 Enterprise 账户）。

astro.config.mjs

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

export default defineConfig({
// ...
  adapter: vercel({
    skewProtection: true
  }),
});

在 Vercel Edge 函数上运行 Astro 中间件

@astrojs/vercel 适配器可以从你代码库中的 Astro 中间件创建一个边缘函数。当 edgeMiddleware 启用时，一个边缘函数将为所有请求（包括静态资源、预渲染页面和按需渲染页面）执行你的中间件代码。

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

这是一个可选功能。要启用它，请将 edgeMiddleware 设置为 true

astro.config.mjs

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

export default defineConfig({
  // ...
  adapter: vercel({
    edgeMiddleware: true,
  }),
});

边缘中间件可以访问 Vercel 的 RequestContext，路径为 ctx.locals.vercel.edge。如果你正在使用 TypeScript，可以通过更新 src/env.d.ts 来使用 EdgeLocals 以获得正确的类型定义

type EdgeLocals = import('@astrojs/vercel').EdgeLocals

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

会话

Astro 会话 API 允许你在请求之间轻松存储用户数据。这可以用于用户数据和偏好设置、购物车和身份验证凭据等。与 Cookie 存储不同，数据没有大小限制，并且可以在不同设备上恢复。

在 Vercel 上使用会话时，你需要为会话存储配置一个驱动程序。你可以从 Vercel 市场安装存储提供商。

例如，如果你已安装一个 Redis 集成并将数据库链接到你的站点

1. 安装 ioredis 包

   npm

   npm install ioredis

   pnpm

   pnpm install ioredis

   Yarn

   yarn add ioredis

2. 使用 Vercel CLI 加载你的环境变量

   vercel env pull .env.local

   这将在你的项目根目录中创建一个 .env.local 文件，其中包含在本地开发时连接到 Redis 数据库所需的环境变量。

3. 配置会话驱动

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import vercel from '@astrojs/vercel';
   
   export default defineConfig({
     adapter: vercel(),
     session: {
       driver: 'redis',
       options: {
         url: process.env.REDIS_URL,
       },
     },
   });

Node.js 版本支持

@astrojs/vercel 适配器支持特定的 Node.js 版本，用于在 Vercel 上部署你的 Astro 项目。要查看 Vercel 上支持的 Node.js 版本，请单击项目的设置选项卡，然后向下滚动到“Node.js Version”部分。

查看 Vercel 文档了解更多信息。

实验性功能

以下功能也可用，但在未来的更新中可能会有破坏性更改。如果你在项目中使用这些功能，请仔细关注 @astrojs/vercel 的更新日志以获取更新。

experimentalStaticHeaders

类型： boolean
默认值： false
适用于： 无服务器

添加于： @astrojs/vercel@8.2.0 新

允许在 Vercel 的配置中为预渲染页面指定自定义请求头。

如果启用，当 Astro 的功能（如内容安全策略）提供静态请求头时，适配器会将其保存在 Vercel 的 vercel.json 文件中。

例如，当实验性的内容安全策略启用时，可以使用 experimentalStaticHeaders 将 CSP headers 添加到你的 Vercel 配置中，而不是创建一个 <meta> 元素。

astro.config.mjs

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

export default defineConfig({
  experimental: {
    csp: true
  },
  adapter: vercel({
    experimentalStaticHeaders: true
  })
});

更多集成

前端框架

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

适配器

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

其他集成

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap