Skip to content

@astrojs/ node

v9.0.0 GitHub npm 更新日志

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

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

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

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

为什么选择 Astro Node.js

标题部分 为什么选择 Astro Node.js

¥Why Astro Node.js

Node.js 是服务器端代码的 JavaScript 运行时。@astrojs/node can be used either in standalone mode or as middleware for other http servers, such as Express.

¥Node.js is a JavaScript runtime for server-side code. @astrojs/node can be used either in standalone mode or as middleware for other http servers, such as Express.

安装

标题部分 安装

¥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 命令添加节点适配器以在你的 Astro 项目中启用 SSR。这将安装 @astrojs/node 并在一个步骤中对你的 astro.config.* 文件进行适当的更改。

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

终端窗口
npx astro add node

手动安装

标题部分 手动安装

¥Manual Install

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

¥First, add the Node adapter to your project’s dependencies using your preferred package manager.

终端窗口
npm install @astrojs/node

然后，将适配器和所需的 按需渲染模式 添加到你的 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 node from '@astrojs/node';


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

配置

标题部分 配置

¥Configuration

@astrojs/node can be configured by passing options into the adapter function.可以使用以下选项：

¥@astrojs/node can be configured by passing options into the adapter function. The following options are available:

模式

标题部分 模式

¥Mode

控制适配器是否构建为 middleware 或 standalone 模式。

¥Controls whether the adapter builds to middleware or standalone mode.

  • middleware 模式允许将构建的输出用作另一个 Node.js 服务器的中间件，例如 Express.js 或 Fastify。

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

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

  • standalone 模式构建到随着入口模块运行而自动启动的服务器。这使你可以更轻松地将构建部署到主机，而无需任何其他代码。

用法

标题部分 用法

¥Usage

首先，执行构建。根据选择的 mode（见上文），执行以下相应步骤：

¥First, performing a build. Depending on which mode selected (see above) follow the appropriate steps below:

中间件

标题部分 中间件

¥Middleware

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

¥The server entrypoint is built to ./dist/server/entry.mjs by default. This module exports a handler function that can be used with any framework that supports the Node request and response objects.

例如，使用 Express：

¥For example, with 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)：

¥Or, with 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.locals 或 Astro 中间件访问的对象：

¥Additionally, you can also pass in an object to be accessed with Astro.locals or in Astro middleware:

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/。

¥Note that middleware mode does not do file serving. You’ll need to configure your HTTP framework to do that for you. By default the client assets are written to ./dist/client/.

独立式

标题部分 独立式

¥Standalone

在独立模式下，服务器在服务器入口点运行时启动。默认情况下，它是按照 ./dist/server/entry.mjs 构建的。你可以使用以下命令运行它：

¥In standalone mode a server starts when the server entrypoint is run. By default it is built to ./dist/server/entry.mjs. You can run it with:

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

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

¥For standalone mode the server handles file serving in addition to the page and API routes.

自定义主机和端口

标题部分 自定义主机和端口

¥Custom host and port

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

¥You can override the host and port the standalone server runs on by passing them as environment variables at runtime:

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

HTTPS

标题部分 HTTPS

默认情况下，独立服务器使用 HTTP。如果你前面有一个执行 HTTPS 的代理服务器，则此方法效果很好。如果你需要独立服务器本身运行 HTTPS，则需要提供 SSL 密钥和证书。

¥By default the standalone server uses HTTP. This works well if you have a proxy server in front of it that does HTTPS. If you need the standalone server to run HTTPS itself you need to provide your SSL key and certificate.

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

¥You can pass the path to your key and certification via the environment variables SERVER_CERT_PATH and SERVER_KEY_PATH. This is how you might pass them in bash:

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

运行时环境变量

标题部分 运行时环境变量

¥Runtime environment variables

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

¥If an .env file containing environment variables is present when the build process is run, these values will be hard-coded in the output, just as when generating a static website.

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

¥During the build, the runtime variables must be absent from the .env file, and you must provide Astro with every environment variable to expect at run-time: VARIABLE_1=placeholder astro build. This signals to Astro that the actual value will be available when the built application is run. The placeholder value will be ignored by the build process, and Astro will use the value provided at run-time.

如果有多个运行时变量，请将它们存储在与 .env 不同的文件（例如 .env.runtime）中。使用以下命令开始构建：

¥In the case of multiple run-time variables, store them in a separate file (e.g. .env.runtime) from .env. Start the build with the following command:

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

资源

标题部分 资源

¥Assets

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

¥In standalone mode, assets in your dist/client/ folder are served via the standalone server. You might be deploying these assets to a CDN, in which case the server will never actually be serving them. But in some cases, such as intranet sites, it’s fine to serve static assets directly from the application server.

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

¥Assets in the dist/client/_astro/ folder are the ones that Astro has built. These assets are all named with a hash and therefore can be given long cache headers. Internally the adapter adds this header for these assets:

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

更多集成

前端框架

SSR 适配器

其他集成

Astro 中文网 - 粤ICP备13048890号