Astro 项目升级全栈：EdgeOne Pages 部署指南

背景介绍

最近用腾讯云的 EdgeOne Pages （下文称 Pages）部署了个人站点，记录一下从 SSG 升级到 SSR 的过程。Pages 是腾讯云推出的网站托管服务，支持 SSR 和边缘函数，国内访问稳定性相比而言会更好一点。Astro 是一个"内容优先"的现代 Web 框架，特别适合博客、文档等内容型网站，默认输出零 JavaScript 的静态 HTML，同时也支持 SSR 模式。我的个人博客就是使用的 Pages 进行托管，Pages 之前只支持 SSG 模式，对初期来说我的站点完全够用了，但随着网站内容增多、访问量上升，我希望通过 SSR 获得更好的 SEO 效果。刚好最近看到 Pages 支持了 Astro 的 SSR 模式，正好借此机会升级并记录实践过程。

基本信息

示例项目

本文使用 demo-portfolio 项目作为示例，一个基于 Astro 的个人作品集网站。项目 fork 自原作者仓库，我对其进行了 Astro 版本升级和 bug 修复，以更好地适配 Pages 的 SSR 模式（欢迎给原作者 star）。

Astro 适配器

适配器（Adapter）是 Astro 用于适配不同部署平台的插件，负责将项目转换为目标平台所需的格式。Pages 提供了官方适配器 @edgeone/astro，支持在边缘计算环境中运行 SSR 模式。

Pages 脚手架

Pages 提供命令行工具，通过 npm install edgeone -g 安装，支持项目初始化、本地调试和一键部署。

实践过程

项目准备

首先从 GitHub 下载示例项目到本地：

bash 复制代码

git clone https://github.com/nuonuo-888/portfolio-sofidev-garrux
cd portfolio-sofidev-garrux
npm install

项目配置

原始 SSG 模式

项目的核心配置文件是 astro.config.mjs，使用 SSG 模式时的配置如下：

javascript 复制代码

import { defineConfig } from "astro/config";
import react from "@astrojs/react";
import tailwind from "@astrojs/tailwind";
import sitemap from "@astrojs/sitemap";

export default defineConfig({
  site: "https://examples.com/", // 网站的部署URL，用于生成sitemap和RSS
  output: "static", // 输出模式：static表示静态站点生成(SSG)
  integrations: [react(), tailwind(), sitemap()], // 集成插件：React组件支持、Tailwind CSS、站点地图生成
});

使用 npm run build 构建后，会在 dist/ 目录生成以下结构：

bash 复制代码

dist/
├── _astro/              # Astro 构建生成的资源文件
├── 404.html            # 404 错误页面
├── about/              # 关于页面
├── assets/             # 静态资源文件（SVG 图标）
├── blog/               # 博客文章目录
├── docs/               # 文档文件
├── img/                # 图片资源
├── index.html          # 首页
├── favicon.svg         # 网站图标
├── sitemap-0.xml       # 站点地图文件
└── sitemap-index.xml   # 站点地图索引

这些文件可以直接部署到任何静态托管服务（如 CDN、对象存储），无需服务器运行时支持。

升级为 SSR 模式

现在我们将项目从 SSG 模式升级为 SSR 模式。首先需要安装 Pages 的适配器：

bash 复制代码

npm install @edgeone/astro

然后修改 astro.config.mjs 配置文件：

javascript 复制代码

import { defineConfig } from "astro/config";
import edgeone from "@edgeone/astro"; // 引入EdgeOne适配器
import react from "@astrojs/react";
import tailwind from "@astrojs/tailwind";
import sitemap from "@astrojs/sitemap";

export default defineConfig({
  site: "https://examples.com/",
  output: "server", // 从 'static' 改为 'server' 启用SSR
  adapter: edgeone(), // 配置EdgeOne适配器
  integrations: [react(), tailwind(), sitemap()],
});

升级为 SSR 模式需要修改两个配置：将 output 从 'static' 改为 'server' 来启用服务端渲染，以及添加 adapter: edgeone() 来配置 EdgeOne 适配器。

配置完成后，执行构建命令：

bash 复制代码

npm run build

构建完成后会在 .edgeone/ 目录生成以下结构：

bash 复制代码

.edgeone/
├── assets/                    # 静态资源文件
└── server-handler/            # 服务器端处理文件

其中 assets/ 目录包含所有静态文件（CSS、JS、图片等），server-handler/ 目录包含服务端渲染代码，用于在 Pages 边缘节点上动态处理请求和渲染页面。

构建产物之所以生成到 .edgeone/ 目录，是因为适配器的作用就是将 Astro 的构建结果转换为目标部署平台所需的格式和目录结构。不同平台的适配器会生成对应的目录，例如 @astrojs/vercel 适配器会生成 .vercel/ 目录，@astrojs/netlify 适配器会生成 .netlify/ 目录，这样各平台的部署工具就能识别并正确部署这些构建产物。

适配器参数配置

@edgeone/astro 适配器支持传入以下参数来自定义构建行为：

includeFiles（可选）：强制包含的文件列表，支持 glob 模式匹配
excludeFiles（可选）：排除的文件列表，主要用于排除 node_modules 中的特定文件，支持 glob 模式匹配

配置示例：

javascript 复制代码

import edgeone from "@edgeone/astro";

export default defineConfig({
  adapter: edgeone({
    outDir: ".edgeone",
    includeFiles: ["src/locales/**", "public/config.json"],
    excludeFiles: ["node_modules/.cache/**"],
  }),
});

注意：根据 Pages 官方文档说明，当前版本暂不支持 Astro 的 Image 组件，请使用常规的 <img> 标签来显示图片。

本地验证

在部署前，建议先在本地运行项目确保一切正常：

bash 复制代码

npm run dev

启动成功后，访问 http://localhost:4321 即可预览网站效果：

确认本地运行无误后，就可以进行部署了。

部署步骤

Pages 提供两种部署方式：

方式一：命令行部署（推荐）

首先全局安装命令行工具：

bash 复制代码

npm install edgeone -g

在项目根目录执行部署命令：

bash 复制代码

edgeone pages deploy --name my-personal-website --token <your-token>

参数说明：

--name：指定项目名称
--token：EdgeOne API Token，用于身份验证（可在 Pages API 管理页面创建）

部署中的输出信息：

ini 复制代码

[cli][✔] Using provided API token for deployment...
[cli][✔] Deploying /Users/your-mac-account-name/*/portfolio-sofidev-garrux/.edgeone to project my-personal-website (Production environment, global area)...
[cli]❗️ Project my-personal-website doesn't exist. Creating new project.
[cli][CreatePagesProject] Creating new project with name: my-personal-website in global area
[cli][✔] Using Project ID: pages-******
[cli]No existing .env file found, will create new one
[cli]Pulling environment variables...
[cli]No environment variables found.
[cli][Uploader] Uploading file: [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
[cli][✔] File uploaded successfully
[cli][✔] Creating deployment in Production environment...
[cli][✔] Created deployment with Deployment ID: ******
[cli][DeployStatus] Deploying.....

部署成功后的输出信息：

ini 复制代码

[cli][✔] Deploy Success
[cli][✔] Deployment to EdgeOne Pages completed successfully! To view your project's live URL.
EDGEONE_DEPLOY_URL=https://my-personal-website.edgeone.site?eo_token=******
EDGEONE_DEPLOY_TYPE=preset
EDGEONE_PROJECT_ID=pages-******
[cli][✔] You can view your deployment in the EdgeOne Pages Console at:
https://console.cloud.tencent.com/edgeone/pages/project/*****

部署成功后，你可以访问 Pages 控制台查看新部署的项目，看到项目列表中出现你的项目即表示发布成功。

在控制台的项目列表中，点击进入你的项目详情页，可以查看项目的预览地址（Preview URL），通过该地址即可访问你部署的网站。

方式二：GitHub 自动部署

访问 Git 项目部署页面，关联 GitHub 账户并选择仓库，配置完成后每次推送代码即可自动触发部署，类似 Vercel、Netlify 的工作流程。

验证 SSR 部署

部署完成后，你可以通过 curl 命令在终端验证 SSR 是否正常工作：

bash 复制代码

curl https://my-personal-website.edgeone.site

如果返回完整的 HTML 内容，说明服务端渲染已成功运行。

通过中间件验证 SSR

为了更直观地验证 SSR 是否正常工作，你可以在项目中添加 Astro 中间件，在响应头中加入自定义信息和服务端渲染时间。

在项目根目录创建 src/middleware.js 文件：

javascript 复制代码

export function onRequest(context, next) {
  // 记录请求开始时间
  const startTime = Date.now();

  // 继续处理请求
  const response = next();

  // 在响应头中添加自定义信息
  response.headers.set("X-Rendered-By", "EdgeOne-Pages-SSR");
  response.headers.set("X-Render-Time", `${Date.now() - startTime}ms`);

  return response;
}

重新构建并部署项目后，使用 curl 命令查看响应头：

bash 复制代码

curl -I https://my-personal-website.edgeone.site

你会在响应头中看到：

makefile 复制代码

X-Rendered-By: EdgeOne-Pages-SSR
X-Render-Time: 15ms

这些自定义响应头证明了页面是在服务端动态渲染的，X-Render-Time 显示了服务端渲染所花费的时间。

总结

以上就是使用 Pages 部署 Astro SSR 项目的全过程。从 SSG 升级到 SSR 的步骤比较简单：安装适配器、修改配置文件、重新构建部署。SSR 模式相比 SSG 在 SEO 和首屏加载上会有一些优势，适合内容型网站。

希望这篇文章能对同样想要将 Astro 项目部署到 Pages 的开发者提供参考，如果遇到问题欢迎在评论区交流。