Astro-服务器渲染

在 Astro 中，静态模式（Static Mode） 和 SSR 模式（Server-Side Render…

在 Astro 中，静态模式（Static Mode） 和 SSR 模式（Server-Side Rendering Mode） 的主要区别在于： 👉 页面是在构建时生成（SSG） 还是 在请求时生成（SSR）。

如果不配置就会：

js
10:09:26 [WARN] [config] This project contains server-rendered routes, but no adapter is installed. This is fine for development, but an adapter will be required to build your site for production.

一、静态模式（Static Mode）

特点：

  • 所有页面在构建时一次性生成为静态 HTML 文件。
  • 部署后无需服务器，只需放在 CDN 或静态网站托管平台（如 Netlify、Vercel、GitHub Pages）。
  • 性能极佳，成本低，无需运行时逻辑。
  • 适合内容固定、不频繁变化的网站，如博客、文档、展示页等。

设定方式（默认模式）：

js
// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static', // 默认即为 static，可省略
});

二、SSR 模式（Server Mode / SSR Mode）

特点：

  • 页面在请求时实时渲染，可访问数据库、API 或动态会话信息。
  • 允许实现登录、个性化、后台管理等功能。
  • 需要一个运行服务器的环境（如 Node.js、Vercel、Netlify Edge、Cloudflare Workers 等）。

设定方式：

js
// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'server', // 启用 SSR 模式
});

三、对比总结

特性静态模式 (Static)SSR 模式 (Server)
页面生成时机构建时请求时
是否需要服务器否是
性能极高依赖服务器性能
动态数据不支持（需预构建）支持（实时获取）
使用场景博客、文档、营销页登录系统、后台管理、个性化内容
配置方式output: 'static'output: 'server'

问题排查

当你执行 npm run dev 时，Astro 并不会真的进行预渲染（prerender）。 开发模式下（dev），Astro 启动的是一个 临时的本地开发服务器， 它会在每次请求页面时重新运行 .astro 文件里的代码块， 而不是像正式构建那样生成静态 HTML 文件。

也就是说：

模式是否重新运行脚本页面是否每次都重新生成随机数是否会变
npm run dev✅ 会✅ 会✅ 每次刷新都会变
npm run build + npm run preview❌ 不会（已预渲染）❌ 固定静态内容❌ 随机数固定

服务器渲染

你的 Astro 项目代码必须经过渲染生成 HTML 才能在网页上显示。

默认情况下，Astro 的页面、路由和 API 端点会在构建时预先渲染为静态页面。但你可以选择让部分或全部路由在请求时由服务器进行按需渲染。

按需渲染的页面和路由会在每次访问时生成，并可为每个访客定制内容。例如，按需渲染的页面可以向已登录用户显示账户信息或展示实时更新的数据，而无需重新构建整个网站。

在请求时由服务端进行的按需渲染也被称为服务端渲染 (SSR)。

服务器适配器

要实现页面按需渲染，需要添加适配器。每个适配器允许 Astro 输出可在特定运行时环境运行的脚本（如 Netlify、Cloudflare），这些环境会在服务器上执行代码以响应请求生成页面。

即使你的站点完全静态且不需要按需渲染任何页面，也建议添加适配器。例如，Netlify 适配器可启用 Netlify 的图片 CDN，而服务端群岛需要安装适配器才能在组件上使用 server:defer。

SSR 适配器

image-20251013112609350

Astro 为 Node.js、Netlify、Vercel 和 Cloudflare 维护官方适配器。你可以在集成目录找到官方和社区适配器，选择与你部署环境匹配的适配器。

添加适配器

使用以下 astro add 命令可添加任何由 Astro 维护的官方适配器集成。该命令将自动安装适配器并修改 astro.config.mjs 文件。

例如，安装 Netlify 适配器可运行：

npx astro add netlify

你也可以手动安装 NPM 包（如 @astrojs/netlify）并自行修改 astro.config.mjs。

注意不同适配器可能有不同的配置选项。请阅读各适配器文档，并在 astro.config.mjs 中为所选适配器应用必要的配置。

启用按需渲染

默认情况下，整个 Astro 站点将预先生成静态 HTML 页面。但你可以选择在需要服务端渲染的路由（如需要检查 cookie 显示个性化内容的页面）上禁用预渲染。

首先，添加适配器集成以在 Astro 项目中启用服务端按需渲染。

然后在需要按需渲染的页面或端点顶部添加 export const prerender = false，其余页面仍保持静态：

src/pages/page-rendered-on-demand.astro

js
---
export const prerender = false
---
<html>
<!--
此内容将按需服务端渲染！
只需为服务器运行时添加适配器集成！
其他所有页面仍会在构建时静态生成！
-->
<html>

以下示例通过禁用预渲染，使端点每次被访问时生成随机数：

src/pages/randomnumber.js

js
export const prerender = false;

export async function GET() {
  let number = Math.random();
  return new Response(
    JSON.stringify({
      number,
      message: `这是一个随机数：${number}`,
    }),
  );
}

'server' 模式

对于高度动态(highly dynamic app)的应用，在添加适配器后，可以将构建输出配置设为 output: 'server' 来默认按需服务端渲染所有页面。这等同于在所有页面上禁用预渲染。

然后，你可以选择对不需要服务端执行的页面（如隐私政策、关于页面）启用预渲染：

src/pages/about-my-app.astro

js
---
export const prerender = true
---
<html>
<!--
配置了 `output: 'server'`，但此页面是静态的！
站点其余部分将按需渲染！
-->
<html>

通过向任意页面或路由添加 export const prerender = true 可预渲染静态页面或端点：

src/pages/myendpoint.js

js
export const prerender = true;

export async function GET() {
  return new Response(
    JSON.stringify({
      message: `这是静态端点`,
    }),
  );
}

注意

建议从默认的 'static' 模式开始，直到确定大部分或全部页面需要按需渲染！这能确保站点保持最佳性能，静态内容无需依赖服务端渲染。

'server' 输出模式不会带来额外功能，仅切换默认渲染行为。

按需渲染特性

https://docs.astro.build/zh-cn/guides/on-demand-rendering/#%E6%8C%89%E9%9C%80%E6%B8%B2%E6%9F%93%E7%89%B9%E6%80%A7

评论

评论加载中……