SST项目中使用Vercel DNS设置根域名记录的注意事项

在SST框架中配置Vercel DNS时，开发者可能会遇到一个常见问题：无法为根域名（apex domain）设置CNAME记录。本文将深入分析这个问题产生的原因，并提供完整的解决方案。

问题背景

当开发者尝试为SST部署的应用配置根域名（如example.com）时，Vercel DNS会拒绝创建CNAME记录。这是因为DNS协议规范中，根域名不允许直接使用CNAME记录类型。错误信息通常会提示："Please specify a name or use an ALIAS Record instead"。

技术原理

1. DNS记录类型限制：

   • CNAME记录不能与同一域名的其他记录共存
   • 根域名通常需要支持多种记录类型（MX、TXT等）
   • 直接使用CNAME会违反DNS规范

2. Vercel的特殊要求：

   • Vercel DNS明确要求根域名必须使用ALIAS记录
   • ALIAS记录是Vercel提供的特殊记录类型，功能类似CNAME但兼容根域名

解决方案演进

初始解决方案

开发者最初通过手动添加transform配置来解决：

transform: {
  record(record) {
    if (record.name === "" && record.type === "CNAME") {
      record.type = "ALIAS"
    }
  },
}

SST框架的官方修复

SST团队在后续版本中内置了这一转换逻辑，当检测到以下条件时会自动转换记录类型：

• 记录名称为空（表示根域名）
• 记录类型为CNAME
• 目标域名与参数中的domain值匹配

实际部署注意事项

1. 部署顺序问题：

   • 修改DNS配置可能需要等待CloudFront证书更新完成
   • 遇到"IllegalUpdate: Only one viewer certificate change may be in progress"错误时，需要间隔一段时间后重试

2. 验证步骤：

   • 部署后检查Vercel DNS控制台确认记录存在
   • 使用dig/nslookup工具验证记录解析是否正确

最佳实践建议

1. 始终使用最新版本的SST框架
2. 对于生产环境，建议先在测试域名上验证配置
3. 记录DNS变更时间，因为全球DNS传播可能需要较长时间

通过理解这些技术细节，开发者可以更顺利地完成SST应用在Vercel平台上的域名配置工作。