完整构建与发布链路

百积木前端使用严格 SemVer 版本发布。project build create --version 由平台创建或复用不可变 Git 标签 v<version>，固定实际完整提交，成功后生成不可变 Artifact。普通站点部署使用同一项目和准确 --version，由平台解析该版本的制品；不需要另行创建项目版本。

本文流程面向普通静态网站。需要平台身份的前端使用 ENVIRONMENT_HOSTED_APP，直接按 平台应用版本创建流程 按版本固定提交、构建并随 Bundle 安装；不先发布外部站点，也不把外部 HTTPS 地址写成平台应用入口。

标准生命周期

前端 Project
  -> 严格 SemVer 版本与不可变 Git 标签
  -> 前端构建任务
  -> 不可变 Artifact（artifactId）
  -> Site
  -> Site Deployment
  -> 当前稳定访问地址
  -> 浏览器端到端验证

具体参数以当前 CLI 和前端构建接口为准。开始前先查看当前能力：

baijimu --version
baijimu workspace project type list --workspace-id <WORKSPACE_ID> --json
baijimu project build --help
baijimu site --help

1. 先选择正确的前端 Project 类型

先执行 baijimu workspace project type list --workspace-id <WORKSPACE_ID> --json，根据目录中的用途和能力选择可用的前端项目类型，并使用返回的真实类型 ID 创建项目。不要根据名称、英文说明或历史按钮配置推断构建能力。

baijimu workspace project create \
  --workspace-id <WORKSPACE_ID> \
  --project-type-id <PROJECT_TYPE_ID> \
  --name <PROJECT_NAME>

初始化归档与初始文件由项目类型目录维护。已有项目使用真实 projectId；不要用名称或列表第一项代替。普通静态网站继续本文流程；需要平台身份或 Runtime 能力的前端使用上文的平台应用交付流程。

2. 完成开发并提交源码

提交依赖锁文件，并确保生产构建不依赖开发机上的未提交文件。发布前至少完成：

• 类型检查、单元测试和生产构建。
• 首页与深层路由的本地预览。
• 公开环境变量使用目标环境值。
• API 地址来自环境配置，不在业务代码中固定测试地址。
• 产物不包含 token、私钥、数据库凭据或内部管理地址。

将源码和锁文件推送并合入项目主线，再选定严格 SemVer 发布版本。首次发布由平台将主线提交固定为 v<version>；标签已存在时使用其固定提交，不会移到新的主线。package.json.version 不代替命令的 --version。历史项目版本映射只作审计，不进入新发布。

构建失败后可按同一版本和相同构建配置重新尝试；源码或构建配置变化时使用新的版本。已成功发布的版本复用其不可变制品。不能移动标签、猜测最新制品或把任务 ID 当作制品 ID。

3. 创建并等待前端构建任务

使用明确的前端构建接口创建任务，无需查询项目类型按钮或传入 functionName。发布版本由 --version 指定，构建参数不传 gitRef、version、projectId 或 workspaceId：

{
  "packageManager": "auto",
  "installCommand": "auto",
  "buildCommand": "pnpm run build",
  "outputDirectory": "dist"
}

baijimu workspace project build create \
  --workspace-id <WORKSPACE_ID> \
  <PROJECT_ID> \
  --version <VERSION> \
  --params @frontend-build.json

调用成功只表示构建任务已经创建。使用返回的真实构建任务 id 查询状态：

baijimu workspace project build status \
  <PROJECT_ID> <JOB_ID> \
  --workspace-id <WORKSPACE_ID> \
  --json

等待任务达到成功终态，核对 releaseVersion、实际源码提交和 Git 标签一致，记录返回的 artifactId 与制品校验值。任务创建成功或进程退出不代表构建成功。普通站点部署使用该准确版本；平台应用版本创建使用成功结果中的 artifactId 与同一完整提交。

4. 创建 Site

Site 是稳定的站点身份，Deployment 是它的一次发布。首次发布前创建 Site；后续版本继续使用同一个 siteKey，不要为每次构建创建新 Site。

baijimu workspace site create \
  --workspace-id <WORKSPACE_ID> \
  <SITE_KEY>

已有 Site 可以直接读取确认：

baijimu workspace site get \
  --workspace-id <WORKSPACE_ID> \
  <SITE_KEY> \
  --json

siteKey、Project 和 Artifact 必须属于目标工作区。不要从另一个工作区复制 ID，也不要从域名格式推导 siteKey。

5. 部署精确版本

用构建成功的项目和同一版本创建 Site Deployment：

baijimu workspace site deployment create \
  --workspace-id <WORKSPACE_ID> \
  <SITE_KEY> \
  --project-id <PROJECT_ID> \
  --version <VERSION>

--version 必须是同一工作区、同一项目已经成功发布的准确版本。平台解析对应不可变 Artifact 并校验其身份、类型和状态；失败时按明确的错误修正源数据，不选择最新制品。

如果站点只发布 Artifact 中的一个子目录，显式增加 --publish-sub-path <RELATIVE_PATH>；默认情况下不要猜测或 重复填写构建输出目录。outputDirectory 属于构建参数，publish-sub-path 属于站点 Artifact 内的发布选择， 两者不是同一个字段。

创建请求返回后，使用真实 deploymentId 等待最终状态，并读取当前发布：

baijimu workspace site deployment get \
  --workspace-id <WORKSPACE_ID> \
  <SITE_KEY> <DEPLOYMENT_ID> \
  --json

baijimu workspace site deployment current \
  --workspace-id <WORKSPACE_ID> \
  <SITE_KEY> \
  --json

只有 Deployment 成功、当前发布指向目标 Deployment，并且真实访问地址通过验证，发布才算完成。

6. 验证真实站点

使用 deployment current 返回的正式地址完成浏览器验证，至少覆盖：

1. 首页可以打开，HTML、脚本、样式和图片均返回成功。
2. 每个深层路由都能直接打开，刷新不会返回 404。
3. 静态资源使用正确基路径；子路径发布时不存在重复或缺失路径前缀。
4. API 请求指向目标环境，且没有把服务 token 或其他长期密钥发送给浏览器。
5. 未登录、权限不足、后端不可用和业务错误都有明确反馈。
6. 发布的制品、源码提交、部署记录和正式地址能够相互对应。
7. 普通站点使用自己的后台授权；站点部署不会创建平台应用版本或授予平台身份。

7. 需要平台能力时的交付流程

普通网站到 Site Deployment 和浏览器验证为止，不需要创建平台应用或 Bundle。 需要平台身份和 Runtime 能力时，把前端放入专属平台应用项目，使用环境托管入口和同源配置 SDK， 按以下链路重新交付，而不是把站点 URL 填入历史外部应用类型：

PLATFORM_APPLICATION 项目、版本与固定提交
  -> ENVIRONMENT_HOSTED_APP 版本内入口
  -> 构建成功取得 artifactId
  -> 以 artifactId + 同一完整提交创建不可变平台应用版本
  -> Bundle 引用精确版本并安装或升级
  -> 平台生成托管入口和同源配置
  -> 验证 PKCE 授权与真实业务调用

完整步骤见 发布并纳入 Bundle。

8. 恢复此前版本

恢复时选择此前已经成功发布并验证的准确版本，再创建一次 Deployment。平台解析旧版本的不可变制品，不重新构建，也不会读取当前主线替换旧内容。

baijimu workspace site deployment list \
  --workspace-id <WORKSPACE_ID> \
  <SITE_KEY> \
  --json

baijimu workspace site deployment create \
  --workspace-id <WORKSPACE_ID> \
  <SITE_KEY> \
  --project-id <PROJECT_ID> \
  --version <PREVIOUS_VERSION>

恢复同样必须等待新 Deployment 成功，并重新执行正式地址、深层路由、API 和权限验证。 此流程只恢复普通站点，不能替代环境托管平台应用的版本创建与 Bundle 安装管理。