Astro Netlify 适配器的 Hosted 测试：直接对真实线上部署做端到端验证

Astro Netlify 适配器的 Hosted 测试：直接对真实线上部署做端到端验证

【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro

这篇指南聚焦 Astro 仓库内@astrojs/netlify适配器的**托管测试（hosted tests）**目录，说明其设计动机、目录结构、夹具项目配置，以及三个真实线上 HTTP 断言的逐行含义。读完你不仅能看懂这套"不跑在本地测试套件里、而是每周打一次真实部署"的 E2E 方案，还能在自己维护的适配器或站点上复刻同样的巡检思路。

什么是 hosted tests：先部署，再对线上站点做断言

在 packages/integrations/netlify/test/hosted/README.md 中，Astro 团队用两句话说明了这类测试的本质：

本文件夹中的测试直接针对一个已部署的 Netlify 网站（托管于 https://curious-boba-495d6d.netlify.app）执行，不会由本地测试套件运行。它们改为每周通过一个 GitHub Action 触发。

它要解决的问题是本地测试永远无法覆盖的盲区：只有当代码真正以"生产部署"形态运行在平台基础设施上时，图片处理端点、边缘中间件上下文传递、SSR 缓存策略等行为才可能被完整验证。README 的原话是"在某种意义上，这是最接近真正的 E2E（as E2E as it gets）"——因为它连被测站点本身都是真实跑在公网上的。

从目录结构上看，这套 hosted 测试与常规本地测试是明确隔离的：

• packages/integrations/netlify/test/development/、functions/、static/属于进入仓库测试套件的本地夹具（fixture）；
• packages/integrations/netlify/test/hosted/则自带独立的部署夹具项目与针对线上 URL 的断言脚本。

此外，这种 hosted 测试思路在仓库内并非孤例——pnpm-lock.yaml 的依赖登记中同样存在packages/integrations/vercel/test/hosted/hosted-astro-project条目，说明 Astro 对各大 serverless/edge 部署平台的适配器采用了相似的验证策略。

目录解剖：测试脚本 + 独立可部署的夹具项目

整个 hosted 目录只有三个组成部分：

test/hosted/ ├── README.md # 说明测试定位与触发方式 ├── hosted.test.ts # 三个针对线上 URL 的断言（node:test） └── hosted-astro-project/ # 真实部署到 Netlify 的夹具站点 ├── astro.config.mjs # output: 'server' + netlify 适配器 ├── netlify.toml # Netlify 构建配置 ├── package.json # 仅依赖 astro 与 @astrojs/netlify（workspace） └── src/ ├── middleware.ts # 中间件，注入 Netlify 上下文与运行时信息 ├── assets/penguin.png # 本地图片，用于图像端点断言 └── pages/ ├── index.astro # 本地 + 远程图片渲染 ├── country.astro # 展示中间件注入的 Geo 国家码 └── time.astro # 输出当前时间戳（验证 SSR 实时性）

关键点是hosted.test.ts 完全不知道项目源码，只认识线上 URL。所有断言都以fetch('https://curious-boba-495d6d.netlify.app/...')为起点，这决定了它天然是黑盒、无任何本地依赖的端到端巡检。

三个线上断言逐行拆解

先看测试文件全文：hosted.test.ts 使用 Node 内置的node:test（而非框架级测试库），以node:assert/strict做断言：

import * as assert from 'node:assert/strict'; import { describe, it } from 'node:test'; const NETLIFY_TEST_URL = 'https://curious-boba-495d6d.netlify.app'; describe('Hosted Netlify Tests', () => { it('Image endpoint works', async () => { const image = await fetch( `${NETLIFY_TEST_URL}/_image?href=%2F_astro%2Fpenguin.e9c64733.png&w=300&f=webp`, ); assert.equal(image.status, 200); }); it('passes context from edge middleware', async () => { const response = await fetch(`${NETLIFY_TEST_URL}/country`); const body = await response.text(); assert.match(body, /has context/); assert.match(body, /Deno/); }); it('Server returns fresh content', async () => { const responseOne: string = await fetch(`${NETLIFY_TEST_URL}/time`).then((res) => res.text()); const responseTwo: string = await fetch(`${NETLIFY_TEST_URL}/time`).then((res) => res.text()); assert.notEqual(responseOne, responseTwo); }); });

1. Image endpoint works：验证 Netlify 按需图片处理链路

请求地址拼出了完整的 on-demand 图片处理参数：

• /_image是 Netlify（Astro assets 集成）对外暴露的图像处理端点；
• href=%2F_astro%2Fpenguin.e9c64733.png中%2F是/的 URL 编码，即请求源图为/ _astro/penguin.e9c64733.png——.e9c64733正是 Astro 构建管线为 src/assets/penguin.png 生成的内容哈希文件名；
• w=300&f=webp表示将原图缩放到 300px 宽并转码为 WebP。

断言只检查status === 200，因为对于线上巡检而言，"端点还活着、能正确返回处理后的图"就足以说明 Astro assets 与 Netlify 图片 CDN 的协作没有被部署配置破坏。这里也顺带覆盖了_astro目录（Astro 默认的静态产物输出目录）在 Netlify 上被正确发布这一事实。

2. passes context from edge middleware：验证 Netlify 边缘上下文透传

/country路由对应 country.astro：

--- const country = Astro.locals.middleware; --- <h1>{country}</h1> <h3>{country ? 'has context' : 'no context'}</h3> <h2>{Astro.locals.runtime}</h2>

页面输出被 middleware.ts 的onRequest决定：

import https from 'node:https'; // @ts-expect-error: Parameter `context` implicitly has an any type export const onRequest = (context, next) => { console.info(context.netlify); context.locals.middleware = context?.locals?.netlify?.context?.geo?.country?.code ?? null; context.locals.runtime = 'Deno' in globalThis ? 'Deno' : 'Node'; context.locals.title = 'Middleware'; context.locals.nodePrefixedImportExists = !!https; return next(); };

中间件做了三件值得注意的事：

1. 读取 Netlify 注入的请求上下文：context.locals.netlify.context.geo.country.code是 Netlify 平台在请求经过时携带的地理信息，将其写入Astro.locals.middleware；
2. 探测运行时：'Deno' in globalThis ? 'Deno' : 'Node'区分当前执行环境；
3. 验证 Node 前缀导入：import https from 'node:https'若能在运行时成功加载，nodePrefixedImportExists就为真，用以确认部署平台支持 Node 内建模块的兼容导入。

于是测试断言body同时匹配/has context/与/Deno/就有了两层含义：

• country.code被成功读入并在页面渲染，页面出现has context；
• Astro.locals.runtime输出为Deno，证明该夹具的中间件实际运行在Netlify Edge（Deno 运行时）而非普通 Node 函数环境。

3. Server returns fresh content：验证 SSR 不被缓存

time.astro 极其简短：

--- const currentTime = new Date().getTime(); --- {currentTime}

测试连续两次请求/time并断言两次响应体不同。由于new Date().getTime()返回毫秒级时间戳，只要两次请求间隔哪怕 1ms，输出就会不同。该断言一旦失败，通常意味着部署端（Netlify CDN/函数层）对 SSR 响应做了意外缓存，导致用户看到过期页面——这正是"部署形态与本地开发不同"的典型差异，也只有 hosted 测试能捕获。

夹具项目的构建与部署配置

hosted 夹具本身是一个标准的 SSR Astro 站点，其部署配置值得逐项研究。

astro.config.mjs：server 输出 + Netlify 适配器

import netlify from '@astrojs/netlify'; import { defineConfig } from 'astro/config'; // https://astro.build/config export default defineConfig({ output: 'server', adapter: netlify({ middlewareMode: 'classic', }), image: { remotePatterns: [ { protocol: 'https', hostname: 'images.unsplash.com', pathname: '/photo-1567674867291-b2595ac53ab4', }, ], }, });

三个配置点各自对应一条测试链路：

• output: 'server'+adapter: netlify(...)：声明站点走 SSR，由 Netlify 适配器生成平台所需的函数/边缘配置，是/country、/time两个动态页面的前提；
• middlewareMode: 'classic'：显式选择经典中间件模式，与上面分析过的边缘中间件执行路径相关；
• image.remotePatterns：允许列表白名单化远程图片源（images.unsplash.com的特定路径）。它配合 index.astro 中对该 Unsplash 图片的<Image>使用，验证远程图片在部署环境下的加载；而本地penguin.png的<Image width={300} />则对应第一个测试中w=300的本地图片处理链路。

--- import { Image } from 'astro:assets'; import penguin from '../assets/penguin.png'; --- <Image src={penguin} width={300} alt="" /> <Image src="https://images.unsplash.com/photo-1567674867291-b2595ac53ab4" width={300} height={400} alt="Astro" />

netlify.toml：声明构建与发布目录

[build] command = "pnpm run --filter @test/netlify-hosted-astro-project... build" publish = "/packages/netlify/test/hosted/hosted-astro-project/dist"

这里有两个细节：

• 构建命令使用 pnpm workspace 过滤：--filter @test/netlify-hosted-astro-project...表明该站点是 Astro pnpm monorepo 中的一个子包（见 package.json，其依赖astro与@astrojs/netlify均为workspace:*），Netlify 在仓库根触发构建时仅构建该子包；
• 发布目录指向dist：astro build的产物目录，Netlify 构建完成后从这里取静态资源上线。

{ "name": "@test/netlify-hosted-astro-project", "version": "0.0.0", "private": true, "type": "module", "scripts": { "build": "astro build" }, "dependencies": { "@astrojs/netlify": "workspace:*", "astro": "workspace:*" } }

整体可见一套闭环：适配器代码更新 → Netlify 自动重新部署curious-boba-495d6d.netlify.app→ 每周 GitHub Action 对线上 URL 跑 hosted.test.ts → 任何在"真实部署形态"下才暴露的回归都会被捕获。

这套设计对测试分层与适配器维护的启示

把 hosted tests 放回 Astro 的测试全貌中看，能清晰看到三层互补结构：

hosted 层恰恰是前两层永远无法替代的"最后一道防线"：它不 mock 平台、不模拟运行时，而是直接把真实请求打到真实公网站点上。对于任何 Netlify 侧的变更（构建路径、平台行为、图片 CDN 策略等），这才是最接近用户真实访问的验证方式。

如何在自己的项目里复刻这套巡检

结合本仓库的落地方式，可在自己的站点上套用同样的模式：

1. 准备一个最小 SSR 夹具：像hosted-astro-project一样，页面分别覆盖图片处理（本地 + 远程）、中间件上下文读取、以及一个每次返回不同时间戳的动态页；
2. 通过 CI/CD 自动部署：让 Netlify（或等价平台）在代码变更后自动重新部署站点，并记录下稳定的线上 URL；
3. 编写纯 HTTP 断言脚本：用node:test或任意 HTTP 测试库，只fetch线上 URL 并断言关键行为（状态码、响应体特征、两次响应是否一致）；
4. 放进定时任务：将测试脚本挂到每周的 GitHub Action 或其他 cron 调度上，与 PR 触发的本地测试套件解耦；
5. 让关键行为失败即报警：例如图片端点status !== 200、边缘上下文丢失、SSR 响应被缓存，这些都应直接导致任务失败，暴露线上回归。

需要注意的是，这类测试依赖一个真实可访问的部署环境，属于"维护成本偏高但覆盖面最真实"的一层，因此更适合作为低频巡检（每周）而非每次提交都跑的快速反馈。理解它的定位后，你就能与本地测试套件合理分工，把不同种类的缺陷挡在正确的阶段之外。

【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro