校验与发布
发布前校验
xdbapp validate
xdbapp validate --list-files
第二条命令会列出即将上传和被排除的文件，适合第一次发布或调整 .xdbpaasignore 后检查。
创建 Preview
xdbapp deploy --message "增加渠道数据看板"
发布过程包括上传、服务端构建、Preview migration（项目声明数据库时）和健康检查。成功后会返回：
- Deployment ID：本次不可变版本的标识；
- Preview URL：本次版本的测试地址；
- 构建和健康状态。
默认 deploy 只发布测试版。即使 CLI 已完成，商家后台的正式应用也不会因此更新；必须先试用，再明确上线同一个 Deployment。
发布到 Production
完成 Preview 验收后：
xdbapp promote <deployment-id> --yes
这一步复用已经构建完成的版本，不会重新上传本地目录。项目声明 database.migrate_command 时，平台会先对 Production 数据库执行 migration；migration 成功并且新运行实例通过健康检查后才切换。失败时当前 Production 继续运行，该 Deployment 保持可重试状态。
直接发布 Production
xdbapp deploy --prod --message "自动化发布"
该命令会创建新版本，在 Preview migration、构建和健康检查成功后继续执行 Production migration，再发布到 Production。建议只用于已有可靠自动化检查的 CI；日常人工操作优先使用 Preview → Promote。
等待时间与机器可读输出
xdbapp deploy --timeout 900 --json
--timeout调整等待构建完成的秒数；--json便于 AI 或 CI 读取结果；--debug会显示更多排查信息，但仍不会回显完整令牌。
就绪后的 JSON 还提供 environment、published、summary 和 nextAction，供 AI 或 CI 区分测试版与正式版。正式上线后提供可取得的 productionUrl；若地址暂时查询失败，应使用 xdbapp status --json 重查，不能把 Preview 地址当成正式地址。
发布失败怎么办
- 运行
xdbapp inspect <deployment-id>查看失败原因； - 查询构建日志：
xdbapp logs --deployment <deployment-id> --type build； - 根据错误修改本地代码；
- 重新运行
xdbapp validate和xdbapp deploy。
失败版本不会替换当前 Production。
如果失败发生在 Production migration，先查询构建日志并修复 migration，再重试 Promote。不要通过手工修改 Production 表结构绕过失败；详细规则见数据库与本地代理。