完整构建与发布链路

百积木站点按“项目＋版本”构建和部署。版本必须与源码根目录 package.json.version 完全一致；平台在首次构建时固定源码，后续重试使用同一份源码。用户和 AI 无需查询或填写 Git SHA。

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

标准生命周期

前端 Project
  -> 严格 SemVer 版本
  -> 项目构建动作
  -> 不可变版本制品
  -> Site
  -> Site Deployment
  -> 当前稳定访问地址
  -> 浏览器端到端验证

具体参数以当前 CLI 和项目类型声明为准。开始前先查看当前能力：

baijimu --version
baijimu project type list --json
baijimu project action --help
baijimu site --help

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

WEB_APPLICATION 是不提供 buildReactProject 和不可变项目版本的旧版通用类型，不能用于新的静态站点发布。 不能根据“网站”这个名称选择它，也不能在创建项目后临时补一个版本号绕过构建。

创建或复用项目前，必须先执行 baijimu project type list --json，按返回的稳定 typeKey 选择；不要使用数字类型 ID。 已有项目还必须执行 baijimu project action list <PROJECT_ID> --json：普通静态网站如果没有 buildReactProject，说明项目类型选错，应新建 REACT_STATIC_APPLICATION 项目并迁移源码，不要继续创建 Site Deployment。

创建普通前端项目：

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

创建请求只声明工作区、稳定项目类型代码和项目基本信息。初始化归档与初始文件由项目类型目录维护； 不要在创建时传入访问范围、模板项目、模板提交或下载地址。项目类型在创建后不可转换；需要另一种项目类型时应创建新项目。

已有项目应直接使用真实 projectId，不要用项目名称或列表第一项代替。项目类型是否可用以及它提供哪些动作， 以当前工作区查询结果为准。

2. 完成开发并声明版本

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

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

在根目录 package.json 中声明本次版本，例如 "version": "1.2.3"，把源码推送并合并到平台项目主线。 构建时填写该版本。首次构建校验主线中的版本并固定源码；一旦绑定，主线继续变化也不会改变该版本。

构建失败或取消后，不修改源码可以使用原版本重试。需要修复源码时，先设置新版本并提交主线，再构建新版本。 平台不会自动修改源码版本，也不允许删除版本后复用同一版本号。

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

先读取项目公开的动作名称和参数 Schema：

baijimu project action list <PROJECT_ID> --json

使用返回的前端构建动作 functionName 创建任务。下面参数文件展示通用 React/Vite 构建；字段必须以动作当前 返回的 parameterSchema 为准：

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

baijimu project action run \
  --workspace-id <WORKSPACE_ID> \
  <PROJECT_ID> <FUNCTION_NAME> \
  --params @frontend-build.json

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

baijimu project action status \
  <PROJECT_ID> <FUNCTION_NAME> <JOB_ID> \
  --json

构建成功后按相同项目版本部署。成功版本的制品不可替换；重复请求会返回已有构建结果。失败时先查看日志，原源码可用原版本重试，修改源码则使用新版本。

4. 创建 Site

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

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

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

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

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

5. 部署项目版本

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

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

--version 不是任意部署标签。它必须已经由同一项目的 buildReactProject 成功登记。若返回 PROJECT_VERSION_NOT_FOUND，不要重试部署：先回到第 3 步完成构建并确认任务成功；如果动作列表中没有 buildReactProject，则按第 1 步更换为正确项目类型。

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

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

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

baijimu 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 版本内入口
  -> CLI 等待构建并冻结平台应用版本
  -> Bundle 引用精确版本并安装或升级
  -> 平台生成托管入口和同源配置
  -> 验证 PKCE 授权与真实业务调用

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

8. 恢复此前版本

恢复时选择此前已经验证的项目版本，再创建一次 Deployment。平台复用该版本的既有制品，不重新构建，也不会读取当前主线替换旧版本：

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

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

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

恢复没有版本号的旧站点制品

版本构建启用前产生的普通静态站点制品没有真实项目版本。仅在恢复这类历史制品时，使用旧构建记录中已经成功的 Artifact ID：

baijimu site deployment restore-artifact \
  --workspace-id <WORKSPACE_ID> \
  <SITE_KEY> <HISTORICAL_ARTIFACT_ID>

该命令只接受旧静态站点制品；新版本统一使用 deployment create --project-id --version。不要把任务编号或 Artifact ID 当作项目版本。