SST项目中Router与StaticSite自定义Bucket的URI处理问题解析

在SST框架中，Router组件与StaticSite组件的结合使用为开发者提供了强大的静态网站路由能力。然而，当StaticSite配置了自定义S3存储桶时，开发者可能会遇到一个隐蔽但影响严重的URI处理问题。本文将深入分析这一问题的成因、影响范围及解决方案。

问题现象

当开发者使用Router组件的routeSite方法路由到配置了自定义Bucket的StaticSite时，CloudFront会返回502错误。核心错误信息显示"CloudFront函数返回了包含无效URI的请求"。仔细检查会发现，生成的URI缺少了起始的斜杠("/")，这违反了HTTP协议和CloudFront的规范要求。

技术背景

SST框架中的Router组件通过CloudFront函数实现动态路由。当请求到达时，该函数会：

1. 解析请求路径
2. 查询内部KV存储确定目标资源位置
3. 重写请求URI指向正确的S3对象
4. 设置适当的S3终端节点

StaticSite组件通常会自动创建专用的S3存储桶，但也支持开发者指定现有的自定义Bucket。这种灵活性正是本问题的触发条件。

问题根源

在Router组件的CloudFront函数实现中，URI重写逻辑存在路径拼接缺陷。具体表现为：

event.request.uri = metadata.s3.dir + baselessUri + v;

这种简单的字符串拼接会：

• 当metadata.s3.dir为空时，baselessUri直接成为URI开头
• 忽略路径组件间的斜杠处理
• 可能产生连续的斜杠或缺少起始斜杠

影响范围

该问题影响以下场景：

1. 多个StaticSite共享同一个S3存储桶
2. 迁移现有S3静态网站到SST架构
3. 需要精细控制Bucket权限和配置的情况
4. 使用base路径配置的嵌套静态网站

值得注意的是，使用StaticSite默认创建的Bucket或直接使用routeBucket方法则不受影响。

解决方案

SST团队在3.11.10版本中修复了此问题。新的URI处理逻辑采用更健壮的实现：

event.request.uri = '/' + [metadata.s3.dir, baselessUri, v]
  .filter(Boolean)
  .join('/')
  .replace(/\/+/g, '/');

这种实现确保了：

1. 强制以斜杠开头
2. 自动处理路径组件间的连接
3. 消除多余的连续斜杠
4. 过滤掉空路径段

最佳实践

为避免类似问题，开发者应注意：

1. 路径处理应始终使用规范化方法，避免简单拼接
2. 测试时应覆盖各种路径组合情况
3. 对于共享Bucket场景，确保路径前缀配置正确
4. 及时更新到最新SST版本获取修复

总结

SST框架的这一修复体现了其对开发者体验的重视。URI处理虽是小细节，却直接影响网站可用性。理解这类问题的成因有助于开发者在类似场景下提前规避问题，构建更健壮的云架构。