跳转到内容

@astrojs/ node

v9.3.1 GitHub npm 更新日志

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

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

为什么选择 Astro Node.js

名为“为什么选择 Astro Node.js”的章节

Node.js 是一个用于服务器端代码的 JavaScript 运行时。@astrojs/node 既可以以独立模式使用，也可以作为其他 http 服务器（如 Express）的中间件使用。

安装

名为“安装”的章节

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

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

终端窗口
npx astro add node

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

手动安装

名为“手动安装”的章节

首先，使用你喜欢的包管理器将 Node 适配器添加到项目的依赖项中。

终端窗口
npm install @astrojs/node

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

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


export default defineConfig({
  adapter: node({
    mode: 'standalone',
  }),
});

配置

名为“配置”的章节

@astrojs/node 可以通过向适配器函数传递选项来进行配置。以下是可用的选项

mode

名为“mode”的章节

类型： 'middleware' | 'standalone'

控制适配器是构建为 middleware（中间件）模式还是 standalone（独立）模式。

  • middleware（中间件）模式允许将构建的输出用作另一个 Node.js 服务器（如 Express.js 或 Fastify）的中间件。
  • standalone（独立）模式会构建一个服务器，在运行入口模块时自动启动。这使你可以更轻松地将构建部署到主机，而无需额外的代码。
astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';


export default defineConfig({
  adapter: node({
    mode: 'middleware',
  }),
});

experimentalDisableStreaming

名为“experimentalDisableStreaming”的章节

类型： boolean
默认值： false

添加于： @astrojs/node@9.3.0 新增

为按需渲染的页面禁用 Astro 默认的 HTML 流式传输。

HTML 流式传输有助于提高性能，并通常提供更好的访客体验。在大多数情况下，不建议禁用流式传输。

然而，当你需要禁用 HTML 流式传输时（例如，你的主机仅支持在 CDN 级别缓存非流式 HTML），你可以选择退出此默认行为

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


export default defineConfig({
  adapter: node({
    mode: 'standalone',
    experimentalDisableStreaming: true,
  }),
});

experimentalStaticHeaders

名为“experimentalStaticHeaders”的章节

类型： boolean
默认值： false

添加于： @astrojs/node@9.3.0 新增

如果启用，当 Astro 的功能（如内容安全策略）提供预渲染页面的标头时，适配器将使用 Response 对象来提供这些标头。

例如，当启用实验性的内容安全策略时，可以使用 experimentalStaticHeaders 将 CSP 标头添加到 Response 对象，而不是创建一个 <meta> 元素

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


export default defineConfig({
  experimental: {
    csp: true
  },
  adapter: node({
    mode: 'standalone',
    experimentalStaticHeaders: true,
  })
});

用法

名为“使用”的章节

首先，执行构建。根据所选的 mode（见上文），请按照以下相应步骤操作

中间件

名为“中间件”的章节

默认情况下，服务器入口点会构建到 ./dist/server/entry.mjs。该模块导出一个 handler 函数，可与任何支持 Node request 和 response 对象的框架一起使用。

例如，与 Express 一起使用

run-server.mjs
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';


const app = express();
// Change this based on your astro.config.mjs, `base` option.
// They should match. The default value is "/".
const base = '/';
app.use(base, express.static('dist/client/'));
app.use(ssrHandler);


app.listen(8080);

或者，与 Fastify (>4) 一起使用

run-server.mjs
import Fastify from 'fastify';
import fastifyMiddie from '@fastify/middie';
import fastifyStatic from '@fastify/static';
import { fileURLToPath } from 'node:url';
import { handler as ssrHandler } from './dist/server/entry.mjs';


const app = Fastify({ logger: true });


await app
  .register(fastifyStatic, {
    root: fileURLToPath(new URL('./dist/client', import.meta.url)),
  })
  .register(fastifyMiddie);
app.use(ssrHandler);


app.listen({ port: 8080 });

此外，你还可以传入一个对象，以便在 Astro 中间件中通过 Astro.locals 访问

run-server.mjs
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';


const app = express();
app.use(express.static('dist/client/'));
app.use((req, res, next) => {
  const locals = {
    title: 'New title',
  };


  ssrHandler(req, res, next, locals);
});


app.listen(8080);

请注意，中间件模式不提供文件服务。你需要配置你的 HTTP 框架来为你完成此操作。默认情况下，客户端资源会写入 ./dist/client/。

独立模式

名为“独立模式”的章节

在独立模式下，当服务器入口点运行时，服务器会启动。默认情况下，它会构建到 ./dist/server/entry.mjs。你可以通过以下方式运行它

终端窗口
node ./dist/server/entry.mjs

对于独立模式，服务器除了处理页面和 API 路由外，还负责文件服务。

自定义主机和端口

名为“自定义主机和端口”的章节

你可以通过在运行时传递环境变量来覆盖独立服务器运行的主机和端口

终端窗口
HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs

HTTPS

名为“HTTPS”的章节

默认情况下，独立服务器使用 HTTP。如果你在其前面有一个执行 HTTPS 的代理服务器，这可以很好地工作。如果你需要独立服务器本身运行 HTTPS，你需要提供你的 SSL 密钥和证书。

你可以通过环境变量 SERVER_CERT_PATH 和 SERVER_KEY_PATH 传递密钥和证书的路径。以下是在 bash 中传递它们的方式

终端窗口
SERVER_KEY_PATH=./private/key.pem SERVER_CERT_PATH=./private/cert.pem node ./dist/server/entry.mjs

运行时环境变量

名为“运行时环境变量”的章节

如果在运行构建过程时存在包含环境变量的 .env 文件，这些值将被硬编码到输出中，就像生成静态网站时一样。

在构建期间，运行时变量必须不在 .env 文件中，并且你必须为 Astro 提供在运行时期望的每个环境变量：VARIABLE_1=placeholder astro build。这向 Astro 表明，在运行构建的应用程序时，实际值将可用。占位符值将被构建过程忽略，Astro 将使用运行时提供的值。

如果存在多个运行时变量，请将它们存储在与 .env 分开的单独文件中（例如 .env.runtime）。使用以下命令启动构建

终端窗口
export $(cat .env.runtime) && astro build

资源

名为“资源”的章节

在独立模式下，dist/client/ 文件夹中的资源通过独立服务器提供。你可能会将这些资源部署到 CDN，在这种情况下，服务器实际上永远不会提供它们。但在某些情况下，例如内网站点，直接从应用程序服务器提供静态资源是可以的。

dist/client/_astro/ 文件夹中的资源是 Astro 构建的。这些资源都以哈希命名，因此可以给予较长的缓存头。适配器内部为这些资源添加了以下标头

Cache-Control: public, max-age=31536000, immutable

会话

名为“会话”的章节

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

使用 Node 适配器时，Astro 使用本地文件系统进行会话存储。如果你希望使用不同的会话存储驱动程序，可以在你的 Astro 配置中指定它。有关更多详细信息，请参阅session 配置参考。

更多集成

前端框架

适配器

其他集成

贡献 社区 赞助