站点清单

站点清单是 Showly 用于了解如何构建、部署和服务站点的文档。它位于导入的工作空间的根目录中，名称为 showly.json。它是每个构建的真实来源——自动检测会在导入时生成初始版本；您可以随时手动编辑它。

除了 rootDirectory 之外，每个字段都是可选的，默认为 .。 Showly 通过自动检测填充合理的默认值，因此最小的有效清单可以是空对象。

文件结构

{
  "rootDirectory": ".",
  "runtime": "node",
  "runtimeVersion": "22",
  "packageManager": "pnpm",
  "installCommand": "pnpm install",
  "buildCommand": "pnpm build",
  "output": {
    "type": "static",
    "directory": "dist"
  },
  "startCommand": "node server.js"
}

字段参考

rootDirectory — 存储库中包含站点的目录。默认为 .。当单个存储库在子目录中保存站点时设置此项。

runtime — 已部署站点的执行运行时。 static、node、rust、go 或 docker 之一。如果省略，Showly将从检测到的框架中推断出来。

runtimeVersion — 运行时版本（例如，Node 主要版本）。 Showly 支持当前Active LTS线路；直播时间为GET /admin/platform/runtime-catalog。

packageManager — 要使用的包管理器（例如，pnpm、npm 或 yarn）。默认为从锁定文件中检测到的值。

installCommand — 安装依赖项的 shell 命令。默认为包管理器的标准安装命令。

buildCommand — 生成可部署工件的 shell 命令。默认为框架的标准构建命令，但您可以提供自己的命令。

output — 构建在何处以及如何发出其工件。具有两个可选键的嵌套对象：type（工件类型）和directory（构建写入的路径，相对于rootDirectory）。

startCommand — 为运行长期进程的运行时启动服务器的命令（例如，node）。静态站点不需要。

框架检测

framework 不是 清单输入 - Showly 自动从 package.json、锁定文件和其他存储库约定中检测到它。检测值是astro、vite、next-export、static-html、custom或unknown之一。如果框架解析为unknown，则构建失败并显示UnsupportedFrameworkError；明确设置runtime和相关命令来部署Showly无法分类的项目。

何时进行手动编辑

• 您更改了构建命令并希望 Showly 跟随。
• 您的存储库在子目录中包含该站点 - 设置 rootDirectory。
• 自动检测猜测运行时错误 - 显式设置 runtime。
• 您的安装或启动命令与包管理器默认命令不同。

验证和失败模式

• 如果 showly.json 无效 JSON，或解析为对象以外的内容，则构建失败并显示 InvalidManifestError。
• 如果框架无法分类（解析为unknown），则构建会失败并显示UnsupportedFrameworkError。

清单不控制的内容

• 环境变量值——这些值是在 Showly UI 中针对每个环境设置的，并存在于秘密存储中。
• 批准规则——这些是工作区政策。
• 部署目标（无服务器容器与静态CDN）——这是部署目标设置。

清单是_构建的样子_。工作区设置是_谁可以对结果执行什么操作_。