🐛 构建报错 NoAdapterInstalled

📋 问题描述

在执行 npm run build 构建命令时，出现以下错误：

[NoAdapterInstalled] Cannot use server-rendered pages without an adapter.
Please install and configure the appropriate server adapter for your final deployment.

🔍 错误信息详情

[NoAdapterInstalled] Cannot use server-rendered pages without an adapter. Please install and configure the appropriate server adapter for your final deployment.
  Hint:
    See https://docs.astro.build/en/guides/on-demand-rendering/ for more information.
  Error reference:
    https://docs.astro.build/en/reference/errors/no-adapter-installed/
  Location:
    H:\astro\grdoc-vue-vite\node_modules\astro\dist\core\build\index.js:87:13

🎯 问题原因

在 astro.config.mjs 配置文件中设置了 output: 'server' 启用 SSR（服务器端渲染）模式，但没有安装和配置对应的服务器适配器（Adapter）。

相关配置代码：

export default defineConfig({
  output: 'server', /* 💕 启用 SSR 服务器端渲染模式 */
  integrations: [vue()]
});

✅ 解决方案

方案一：安装 Node.js 适配器（推荐用于 Node.js 部署）

如果需要在 Node.js 环境中运行（如自建服务器、VPS 等），安装 @astrojs/node 适配器：

1️⃣ 安装适配器

npm install @astrojs/node

2️⃣ 修改配置文件

编辑 astro.config.mjs 文件，添加 Node.js 适配器配置：

// @ts-check
import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
import node from '@astrojs/node'; /* ◀️ 导入 Node.js 适配器 */

// https://astro.build/config
export default defineConfig({
  output: 'server', /* 💕 启用 SSR 服务器端渲染模式 ◀️ 提升首屏性能和 SEO */
  adapter: node({
    mode: 'standalone' /* 🔗 使用独立模式运行 Node.js 服务器 ◀️ 适合独立部署 */
  }),
  integrations: [vue()]
});

3️⃣ 重新构建

npm run build

4️⃣ 启动生产服务器

node ./dist/server/entry.mjs

方案二：改为静态生成（推荐如果不需要 SSR）

如果不需要服务器端渲染功能，可以将项目改为静态生成模式：

修改配置文件

编辑 astro.config.mjs 文件，将 output 改为 static：

export default defineConfig({
  output: 'static', /* 💕 改为静态生成模式 ◀️ 无需适配器 */
  integrations: [vue()]
});

或者删除 output 配置项（默认为静态模式）：

export default defineConfig({
  integrations: [vue()]
});

方案三：其他适配器选择

根据部署目标选择其他适配器：

📁 构建输出说明

使用 Node.js 适配器构建后，输出目录结构：

dist/
├── server/          /* ◀️ 服务器端代码 */
│   └── entry.mjs   /* ◀️ 服务器入口文件 */
└── client/          /* ◀️ 静态资源（CSS、JS、图片等） */

🚀 部署方式

独立模式（standalone）

# 构建
npm run build

# 启动服务器
node ./dist/server/entry.mjs

默认监听端口：4321

自定义端口

PORT=3000 node ./dist/server/entry.mjs

💡 最佳实践

1. 选择合适的模式

   • 需要动态数据、用户认证 → 使用 SSR + 适配器
   • 纯内容展示、博客类 → 使用静态生成

2. 适配器选择

   • 自有服务器/VPS → @astrojs/node
   • Serverless 平台 → 选择对应平台的适配器

3. 环境变量

   • 生产环境配置通过环境变量传递
   • 不要在代码中硬编码敏感信息

📚 参考链接

• Astro 服务端渲染官方文档
• NoAdapterInstalled 错误说明
• @astrojs/node 适配器文档

🕊️ 白木 原创开发 🔗 gl.baimu.live