部署与适配器

Astro 支持部署到各种托管平台，从传统的 Node.js 服务器到现代的 Serverless 环境。通过适配器（Adapter），Astro 可以将 SSR 输出适配到不同的运行时环境，实现零配置部署到主流平台。

适配器概述

适配器是连接 Astro SSR 输出与目标运行时的桥梁。每个适配器负责处理特定平台的部署要求。

可用适配器

平台	适配器包	类型	说明
Vercel	`@astrojs/vercel`	Serverless	支持 Edge Functions、ISR
Netlify	`@astrojs/netlify`	Serverless	Functions + Edge
Cloudflare	`@astrojs/cloudflare`	Edge	Workers/Pages
Node.js	`@astrojs/node`	传统服务器	通用适配
Deno	`@astrojs/deno`	Deno Deploy	Deno 运行时
Bun	`@astrojs/bun`	Bun 运行时	高速运行时

Node.js 适配器

安装与配置

bash

pnpm add @astrojs/node

javascript

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

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

部署模式

standalone 模式：

生成独立的 Node.js 服务器
适合传统的 VPS、云服务器
包含内置的静态文件服务

middleware 模式：

仅生成中间件代码
需要配合现有 Express/Fastify 服务器
适合将 Astro 集成到现有应用

构建与运行

bash

# 构建
pnpm build

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

# 或使用自定义端口
HOST=0.0.0.0 PORT=8080 node dist/server/entry.mjs

Docker 部署

dockerfile

# Dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install
COPY . .
RUN pnpm build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./
RUN corepack enable && pnpm install --prod

EXPOSE 4321
CMD ["node", "dist/server/entry.mjs"]

bash

# 构建镜像
docker build -t my-astro-site .

# 运行容器
docker run -p 4321:4321 my-astro-site

Vercel 适配器

安装

bash

pnpm add @astrojs/vercel

配置

javascript

// astro.config.mjs
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'hybrid',
  adapter: vercel({
    // 图像优化服务
    imageService: true,

    // 边缘函数（Edge Functions）
    // middleware: true,  // 使用 Edge Functions 作为中间件
  }),
});

部署方式

方式一：通过 Vercel CLI

bash

# 安装 Vercel CLI
npm i -g vercel

# 登录
vercel login

# 部署预览
vercel

# 生产部署
vercel --prod

方式二：通过 Git 集成

将代码推送到 GitHub/GitLab/Bitbucket
在 Vercel 仪表盘中导入项目
配置构建命令（pnpm build）和输出目录（dist）
自动部署

Edge Functions

javascript

// astro.config.mjs
import vercel from '@astrojs/vercel/edge';

export default defineConfig({
  output: 'server',
  adapter: vercel({
    runtime: 'edge',  // 使用 Edge Functions
  }),
});

Netlify 适配器

安装

bash

pnpm add @astrojs/netlify

配置

javascript

// astro.config.mjs
import netlify from '@astrojs/netlify';

export default defineConfig({
  output: 'hybrid',
  adapter: netlify(),
});

部署

bash

# 通过 CLI 部署
npm install -g netlify-cli
netlify login
netlify init
netlify deploy --prod

Netlify Functions

typescript

// src/pages/api/hello.ts
export const prerender = false;

export const GET = () => {
  return new Response(JSON.stringify({ message: 'Hello from Netlify!' }), {
    headers: { 'Content-Type': 'application/json' },
  });
};

Cloudflare 适配器

安装

bash

pnpm add @astrojs/cloudflare

配置

javascript

// astro.config.mjs
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    // 平台配置
    platformProxy: {
      enabled: true,
    },
  }),
});

Cloudflare Pages 部署

bash

# 安装 Wrangler CLI
npm install -g wrangler

# 预览部署
wrangler pages dev dist

# 生产部署
wrangler pages deploy dist

Cloudflare Workers

javascript

// astro.config.mjs
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    mode: 'directory',  // 部署为 Workers
  }),
});

环境变量管理

定义环境变量

bash

# .env 文件（本地）
PUBLIC_SITE_NAME="My Blog"
API_BASE_URL="https://api.example.com"
SECRET_API_KEY="sk-xxxx"

访问环境变量

astro

---
// 服务端代码（fullmatter、API 端点）
const apiKey = import.meta.env.SECRET_API_KEY;

// 客户端代码
const siteName = import.meta.env.PUBLIC_SITE_NAME;
---

<!-- 客户端可访问 PUBLIC_ 开头的变量 -->
<script>
  console.log(import.meta.env.PUBLIC_SITE_NAME);
</script>

构建时 vs 运行时

javascript

// 仅构建时可用（build time）
const buildTime = import.meta.env.BUILD_TIME; // 在 astro.config.mjs 中定义

// 服务端运行时可用
const secret = import.meta.env.SECRET_KEY; // API 端点、中间件

// 客户端可见
const publicVar = import.meta.env.PUBLIC_VAR; // PUBLIC_ 前缀

Vercel 环境变量

plaintext

# Vercel 仪表盘设置
SITE_NAME=My Blog
PUBLIC_SITE_NAME=My Blog  # PUBLIC_ 前缀暴露给客户端
API_KEY=sk-xxx            # 服务端专用

Netlify 环境变量

bash

# 通过 CLI 设置
netlify env:set PUBLIC_SITE_NAME "My Blog"
netlify env:set API_KEY "sk-xxx"

# 通过 .env.production 文件
# netlify.toml
[build.environment]
  NODE_VERSION = "20"

生产构建优化

构建配置

javascript

// astro.config.mjs
export default defineConfig({
  build: {
    // 内联体积较小的 CSS
    inlineStylesheets: 'auto',

    // 静态资源输出目录
    assets: 'assets',

    // 清理构建目录
    cleanoutDir: true,
  },

  vite: {
    build: {
      // CSS 代码分割
      cssCodeSplit: true,

      // 禁用 console 和 debugger
      minify: 'terser',
      terserOptions: {
        compress: {
          drop_console: true,
          drop_debugger: true,
        },
      },
    },
  },
});

静态资源优化

javascript

// astro.config.mjs
export default defineConfig({
  build: {
    assets: '_assets',
  },
  compressHTML: true,
});

CDN 边缘部署

Cloudflare Pages 完整示例

javascript

// astro.config.mjs
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'hybrid',
  adapter: cloudflare({
    imageService: true,
    platformProxy: {
      enabled: true,
    },
  }),
  vite: {
    build: {
      assets: '_assets',
    },
  },
});

边缘缓存配置

javascript

// wrangler.toml (Cloudflare Pages)
name = "my-astro-site"
compatibility_date = "2024-01-01"

# 页面规则配置
[[headers]]
  for = "/static/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-Content-Type-Options = "nosniff"
    Referrer-Policy = "strict-origin-when-cross-origin"

Vercel 缓存配置

json

// vercel.json
{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    },
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        },
        {
          "key": "X-Content-Type-Options",
          "value": "nosniff"
        }
      ]
    }
  ]
}

调试与预览

本地预览构建结果

bash

# 构建
pnpm build

# 预览
pnpm preview

# 指定端口
pnpm preview --port 8080

调试 API 端点

bash

# 开发模式
pnpm dev

# 构建并以 SSR 模式运行
node dist/server/entry.mjs

# 或使用 node --inspect 调试
node --inspect dist/server/entry.mjs

日志查看

typescript

// src/pages/api/debug.ts
export const prerender = false;

export const GET: APIRoute = async ({ request }) => {
  console.log('Request headers:', request.headers);
  console.log('URL:', request.url);

  return new Response(JSON.stringify({
    url: request.url,
    method: request.method,
  }), {
    headers: { 'Content-Type': 'application/json' },
  });
};

部署平台选择指南

plaintext

场景                          推荐平台
─────────────────────────────────────────────────────────────
静态网站 / 博客               Vercel / Netlify / Cloudflare Pages
需要 SSR 的应用               Vercel / Netlify / Cloudflare Workers
需要数据库                    Railway / PlanetScale / Supabase
电商网站                      Vercel Commerce / Shopify
企业内部应用                   Docker (Node.js) / VPS
边缘计算 / 低延迟             Cloudflare Workers / Vercel Edge

总结

本文全面介绍了 Astro 的部署与适配器相关内容：

适配器体系：Node.js、Vercel、Netlify、Cloudflare 等主流平台支持
部署流程：构建 → 配置适配器 → 部署到目标平台
环境变量：import.meta.env 访问，支持构建时和运行时变量
生产优化：compressHTML、CSS 内联、静态资源优化
CDN 边缘：Cloudflare Workers、Vercel Edge Functions
调试预览：pnpm preview 本地预览，--inspect 远程调试

至此，Astro 5.x 完整学习路线系列文章全部完成！从项目初始化、组件开发、内容集合、路由系统，到 MDX 集成、渲染模式、岛屿架构、View Transitions，再到国际化、API 端点和部署适配器，涵盖了 Astro 开发的各个方面。建议通过 「审核 astro」 命令启动审核角色检查文章质量。

部署与适配器

适配器概述

可用适配器

Node.js 适配器

安装与配置

部署模式

构建与运行

Docker 部署

Vercel 适配器

安装

配置

部署方式

方式一：通过 Vercel CLI

方式二：通过 Git 集成

Edge Functions

Netlify 适配器

安装

配置

部署

Netlify Functions

Cloudflare 适配器

安装

配置

Cloudflare Pages 部署

Cloudflare Workers

环境变量管理

定义环境变量

访问环境变量

构建时 vs 运行时

Vercel 环境变量

Netlify 环境变量

生产构建优化

构建配置

静态资源优化

CDN 边缘部署

Cloudflare Pages 完整示例

边缘缓存配置

Vercel 缓存配置

调试与预览

本地预览构建结果

调试 API 端点

日志查看

部署平台选择指南

总结

评论

Related Articles

内容集合（Content Collections）深度解析

部署与适配器

API 端点与后端集成