Astro 系列（九）：Middleware、API 端点与认证

astromiddlewareapiauthedge

Astro 入门与实战 系列导航

  1. （一）Astro 是什么，解决什么问题
  2. （二）项目结构与开发约定
  3. （三）Island 架构——为什么默认零 JavaScript
  4. （四）内容驱动还是应用驱动——Astro 的边界
  5. （五）SSR 还是 SSG，怎么选
  6. （六）集成生态——从官方到社区
  7. （七）能用 Astro 做什么——扩展玩法全景
  8. （八）View Transitions——让 MPA 拥有 SPA 体验
  9. （九）Middleware、API 端点与认证 ← 当前
  10. （十）第三方服务拼装——评论、搜索、分析
  11. （十一）框架对比（上）——全栈方向
  12. （十二）框架对比（下）——静态站点方向
# Middleware、API 与认证 ## Middleware 机制 ### 请求/响应拦截 ### 语言检测 ### A/B 测试 ### 访问控制 ## API 端点 ### 文件路由 API ### REST 设计模式 ### JSON 响应 ### 流式响应 ## 认证策略 ### JWT 方案 ### OAuth 集成 ### Session Cookie ### 中间件层实现 ## 边缘 Middleware ### 轻量级请求处理 ### 限流 ### IP 过滤 ### 与边缘平台的集成

Middleware：请求进入页面之前的关卡

Middleware 是 Astro 在 3.0 引入的功能。它允许你在请求到达页面之前执行逻辑——类似 Express 的中间件概念，但更轻量，专为页面路由设计。

Middle 的执行位置在请求生命周期的前端：

flowchart LR A[浏览器请求] --> B[Middleware] B --> C{条件判断} C -->|放行| D[页面渲染] C -->|重定向| E[3xx 响应] C -->|拦截| F[4xx/5xx 响应] D --> G[返回 HTML]

典型用途：

  • 认证守卫：未登录用户访问 /admin 时重定向到登录页
  • 国际化路由：检测 Accept-Language 头，重定向到 /zh/ 或 /en/
  • A/B 测试：根据 cookie 将流量分配到不同版本的页面
  • 日志和监控：记录每个请求的耗时、状态码

API 端点：不止是 HTML

Astro 的路由系统不仅输出 HTML，也可以输出 JSON。在 src/pages/api/ 下创建 .ts 或 .js 文件，它们会成为 API 端点：

  • src/pages/api/search.json.ts → GET /api/search.json
  • src/pages/api/admin/save.ts → POST /api/admin/save

这些端点可以直接访问文件系统、查询数据库、调用第三方 API。它们运行在服务端，不会向客户端暴露任何实现细节。

API 端点 + Middleware 的组合让 Astro 具备了完整的后端能力——对于中小型项目，可能不需要单独的 BFF 层。

认证策略全景

JWT（JSON Web Token）：登录后服务端签发 token，客户端存储在 cookie 或 localStorage。每次请求附带 token，Middleware 验证签名。适合 API 优先的应用。

OAuth 2.0 / OIDC：通过第三方（GitHub、Google、Auth0）认证。用户跳转到第三方登录页，回调时服务端用 code 换取用户信息。适合需要社交登录或企业 SSO 的场景。

Session Cookie：传统方案。服务端维护 session store（内存/Redis），客户端只持有 session ID。适合 SSR 页面，可以服务端直接读取用户状态。

Astro 的推荐组合：Session Cookie + Middleware 守卫。在 Middleware 中检查 cookie，将用户信息注入到页面 context，页面可以直接使用。

边缘 Middleware 的特殊考虑

当 Astro 部署到 Cloudflare Workers 或 Deno Deploy 等边缘平台时，Middleware 运行在全球边缘节点上。这带来了独特的优势：

  • 超低延迟：认证检查在全球最近的节点完成
  • 减轻源站压力：大部分认证逻辑在边缘完成

但也有约束：

  • 无法访问 Node.js 原生模块（如 fs、crypto 的某些方法）
  • 运行时内存和 CPU 时间有限
  • 需要选择边缘兼容的库

对于大多数内容站点，这些约束不是问题——认证逻辑通常足够轻量。

延伸阅读

实操清单

  • 创建一个简单的 Middleware，验证某个路由的访问控制
  • 在 src/pages/api/ 下创建一个 JSON 端点
  • 选择一个认证方案（JWT 或 Session），理解其工作流
  • 如果有部署到边缘平台的需求，检查所用库的兼容性

created by:codex on deepseek v4 pro