Vercel自定义域名与别名区别及GitHub Actions别名分配问题排查

一、定义与区别 #

• 自定义域名（Custom Domain）：绑定到Vercel项目/团队的顶级/二级域名，属于静态配置。添加后需完成DNS解析验证，长期关联到特定环境（生产/预览）或分支，是域名在Vercel体系内的基础绑定关系。
• 别名（Alias）：动态分配给单个部署实例的域名映射，常用于临时指向预览部署、分支部署等场景。基于已存在的自定义域名生效，无需额外DNS验证，可随时更换或移除。
• 二者并非同一事物：自定义域名是基础绑定载体，别名是基于该载体的动态指向规则。

二、API分配别名失败的原因判断 #

是的，冲突大概率来自你已在Vercel控制台将example.com静态绑定到preview环境或release分支。

Vercel的核心规则是：同一个自定义域名不能同时存在静态环境/分支绑定和动态别名分配两种配置。当你在控制台配置了release分支的域名设置，相当于把example.com固定关联到该分支的默认部署，此时调用API分配该域名作为别名会触发冲突校验，导致操作失败。

三、解决方案 #

1. 先在Vercel控制台移除release分支（或preview环境）的静态域名绑定，确保example.com仅作为自定义域名存在于项目/团队中，未被固定关联到任何环境或分支。
2. 在GitHub Actions工作流中调用Vercel的“分配别名”API，将example.com指向release分支的目标部署实例。
3. 若需保留原有静态绑定，可改用子域名（如release.example.com）作为别名，避免与主域名的静态配置冲突。

内容的提问来源于stack exchange，提问作者Shivam Srivastava