> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 静态托管

> 将构建好的静态网站发布到阶跃星辰开放平台，生成预览和线上访问链接

静态托管可以将已经构建好的静态网站发布到阶跃星辰开放平台，并生成可预览、可分享的链接。无需准备服务器或配置 CDN，上传网站文件后即可完成预览、上线和版本管理。

本文面向使用阶跃星辰开放平台「我的站点」功能的产品用户，介绍从首次发布到日常运维的完整流程。

<Note>
  如需通过命令行、CI/CD 或 MCP 部署和管理站点，请参阅[静态托管 CLI 与 MCP](/docs/zh/guides/developer/page-hosting-cli-mcp)。
</Note>

## 适用场景

* 产品官网、活动页、帮助中心、作品集等静态网站。
* 使用 React、Vue、Vite、Next.js 静态导出等工具构建后的产物。
* 需要在正式上线前分享预览链接，或需要保留多个可回滚版本的场景。

静态托管只负责静态文件分发，不提供服务端运行时。PHP、Python、Node.js 等服务端代码不会在托管环境中执行。

## 核心概念

| 概念   | 说明                                        |
| ---- | ----------------------------------------- |
| 站点   | 一个独立的网站项目，包含名称、访问地址、服务模式和多个版本。            |
| 版本   | 一次发布产生的文件快照，按 `v1`、`v2`……递增。版本可以预览、上线或回滚。 |
| 预览链接 | 指向指定版本的临时分享地址。预览不改变线上版本，可设置有效期或撤销。        |
| 线上版本 | 当前对外正式提供服务的版本。一个站点同一时间只有一个线上版本。           |
| 根页面  | 访问站点根路径 `/` 时返回的文件，通常是 `index.html`。      |

## 快速开始

### 1. 打开「我的站点」

登录[阶跃星辰开放平台](https://platform.stepfun.com)后，在控制台侧边栏进入「我的站点」，点击「新建站点」。

站点列表支持按名称搜索，并按「全部」「已上线」「草稿」「异常」筛选。

### 2. 准备并上传网站产物

在「发布站点」窗口中填写站点标题，然后将以下任一种内容拖入上传区域，或点击对应按钮选择：

* 单个 `.zip` 压缩包；
* 一个网站文件夹；
* 多个网站文件。

上传文件夹时，系统会自动去除最外层的公共目录。例如选择 `dist/` 文件夹后，`dist/index.html` 会按 `index.html` 发布。

### 3. 确认根页面

如果上传内容中包含根目录下的 `index.html`，系统会自动将它作为根页面。

如果没有 `index.html`，系统会列出可选文件：

* 选择一个 HTML 文件，访问 `/` 时返回该文件；
* 选择「无根页面」，访问 `/` 时返回 404。

ZIP 压缩包不能在上传窗口中逐文件选择根页面；请在压缩包根目录放置 `index.html`。压缩包内没有该文件时，发布会失败。

### 4. 生成预览并上线

点击「发布」后，系统会依次上传文件、处理版本并生成预览链接。发布成功后会显示「预览就绪」：

1. 点击「打开预览」检查页面和资源是否正常；
2. 在版本历史中找到需要发布的版本，点击「上线」；
3. 确认后，该版本会替换当前线上版本。

首次发布默认只生成预览，不会自动替换线上版本。线上地址会在首次上线后显示在站点详情页和站点卡片中。

## 上传要求与限制

### 文件大小和数量

* 单次发布整包大小不超过 **50 MB**；
* 单次发布文件数不超过 **5,000 个**；
* 站点名称最多 **64 个字符**；
* 每个站点最多保存的版本数受账户配额限制，达到上限后请先删除旧版本（如果产品界面提示该限制）。

`.zip` 的限制按压缩包文件大小检查；压缩包解开后，文件类型和路径仍由服务端再次校验。

### 支持的文件类型

常见支持类型包括：

`html`、`htm`、`css`、`js`、`mjs`、`json`、`map`、`txt`、`xml`、`svg`、`ico`、`png`、`jpg`、`jpeg`、`gif`、`webp`、`avif`、`woff`、`woff2`、`ttf`、`otf`、`eot`、`wasm`、`pdf`、`mp4`、`webm`、`mp3`、`wav`、`md`、`markdown`、`jsonl`、`tsx`、`jsx`。

以下类型明确禁止：

`php`、`py`、`exe`、`sh`、`bat`、`cmd`、`dll`、`so`、`jsp`、`asp`、`aspx`、`cgi`、`pl`。

扩展名不在支持列表中的文件也会被拒绝。建议上传构建工具生成的 `dist` 或 `build` 目录，不要上传源代码、依赖目录（如 `node_modules`）或服务端文件。

## 预览、上线与版本管理

### 预览链接

每次发布都会为新版本生成预览链接。预览链接支持以下操作：

* 打开链接检查页面；
* 复制链接并分享给协作者；
* 设置有效期：永不过期、24 小时、7 天或 30 天；
* 撤销链接；
* 撤销后重新生成新链接。

预览链接只代表对应版本的预览，不等于线上地址。链接撤销后会立即失效，访问返回 404；设置了有效期的链接到期后同样不可访问。

### 上线

在站点详情页的「历史版本」中，打开版本操作菜单并点击「上线」。上线前会弹出确认提示，因为上线会替换当前线上版本。

只有未上线且未被审核标记为拒绝的版本可以尝试上线；最终结果以服务端校验为准。审核未通过或配置解析失败的版本不能上线。

### 回滚

如果新版本出现问题，在「历史版本」中找到之前的版本，打开操作菜单并点击「回滚」。确认后，选中的版本会成为新的线上版本，原线上版本仍保留在历史记录中。

### 重新发布

站点详情页右上角的「重新发布」有两种用法：

* **不上传新文件**：重新激活当前线上版本，适合线上地址异常或需要再次触发上线的场景；
* **上传新文件**：创建一个新版本。新版本先生成预览，检查无误后再上线。

如果修改了环境变量，必须上传新的构建产物并发布新版本，直接重新上线旧版本不会使用最新环境变量。

## 服务模式

在站点详情页进入「站点设置」，可以选择服务模式：

* **SPA**：未知路由返回根页面（通常是 `index.html`），适合 React Router、Vue Router 等客户端路由应用。刷新 `/about` 等前端路由时，仍由前端应用接管路由。
* **Static**：请求缺失文件时直接返回 404，适合路径与文件一一对应的普通静态网站。

切换服务模式会立即保存。若应用使用前端路由，建议选择 SPA；若希望错误路径明确返回 404，建议选择 Static。

## 自定义响应头

在上传包的**根目录**放置 `page.config.json`，可以为不同路径配置响应头。示例：

```json theme={null}
{
  "headers": [
    {
      "path": "/*",
      "name": "X-Frame-Options",
      "value": "DENY"
    },
    {
      "path": "/assets/*",
      "name": "Cache-Control",
      "value": "public, max-age=31536000, immutable"
    }
  ]
}
```

| 字段      | 说明                           |
| ------- | ---------------------------- |
| `path`  | 规则匹配的路径，例如 `/*`、`/assets/*`。 |
| `name`  | 响应头名称，例如 `Cache-Control`。    |
| `value` | 响应头值。                        |

发布后在「响应头规则」页签可以查看当前线上版本解析出的规则。该页签展示的是只读结果，修改规则需要更新 `page.config.json` 后重新发布。配置无法解析时，该版本会被标记为配置拒绝，不能上线。

## 构建时环境变量

### 配置变量

在「站点设置」的「环境变量」区域添加变量。变量名必须：

* 以大写英文字母开头；
* 只包含大写英文字母、数字和下划线，例如 `API_BASE_URL`；
* 同一站点内不能重复；
* 最多配置 50 个变量；
* 单个变量值为单行文本，最多 2,048 个字符。

### 在文件中引用

在静态文件中使用 <code>{'{{PAGE_ENV:变量名}}'}</code> 占位符。例如：

```js theme={null}
const apiBase = '{{PAGE_ENV:API_BASE_URL}}'
```

发布构建时，系统会在文本文件中将占位符替换为对应值。当前处理的文本类型包括：`.html`、`.htm`、`.js`、`.css`、`.json`、`.txt`、`.svg`、`.xml`。图片、字体、音视频、PDF 等二进制文件不会被修改；未定义的占位符会保持原样。

环境变量在**发布构建时注入**，保存变量后不会改写已经发布的版本。变更变量后，请重新上传并发布产物；仅对旧版本执行「重新发布」不会生效。

不要把密码、私钥、长期有效的访问令牌等高敏感信息放入前端环境变量。静态文件会发送给访问者，构建后的变量值也可能被用户在浏览器中看到。

## 数据分析与部署日志

进入站点详情页的「数据分析」页签，可以查看：

* 请求数；
* 传输流量；
* 每日请求趋势；
* 部署日志（版本、操作、操作者、时间和结果）。

数据分析支持 `24h`、`7d`、`30d` 三个时间范围。新站点或尚未产生访问请求的站点会显示空状态；分享线上地址或预览地址产生访问后，再返回查看统计数据。

## 站点设置与删除

「站点设置」支持：

* 修改站点名称；
* 切换 SPA / Static 服务模式；
* 管理环境变量；
* 删除站点。

删除站点需要在确认框中完整输入站点名称。删除是永久操作，会同时删除站点及其所有版本，且线上地址和预览链接都会失效。删除前请先通过版本下载功能备份仍可用的版本文件。

## 常见问题

### 访问 `/` 返回 404

请确认：

1. 上传包根目录存在 `index.html`；
2. 如果使用文件/文件夹上传，已在「根页面」中选择正确文件；
3. 没有选择「无根页面」；
4. 站点已经上线，而不是仅生成了预览版本。

### 刷新前端路由返回 404

将站点服务模式改为 SPA，并重新访问线上地址。Static 模式只会返回实际存在的文件。

### 发布提示文件类型不支持

检查报错列出的文件名或扩展名，移除禁止类型和不在支持列表中的文件后重新打包。ZIP 内的文件也会被检查；请特别注意不要把服务端源码或脚本放入压缩包。

### 环境变量没有更新

环境变量是构建时替换。确认变量已保存，然后上传新的静态产物并发布新版本；直接对旧版本执行「重新发布」不会重新注入变量。

### 预览链接打不开

检查链接是否已过期或被撤销，并在版本操作中重新生成链接。若版本已经删除或站点被删除，原链接也无法恢复。

### 新版本无法上线

查看版本上的状态标签：审核未通过、审核提交失败或 `page.config.json` 配置拒绝都会阻止上线。修复网站内容或配置后，重新发布一个新版本。

## 发布前检查清单

* [ ] 入口文件和资源路径使用相对路径，大小写与实际文件名一致。
* [ ] 根目录包含 `index.html`，或已明确选择其他根页面。
* [ ] 根据应用类型选择 SPA 或 Static 服务模式。
* [ ] 已移除 `node_modules`、源代码和服务端脚本等不需要发布的文件。
* [ ] 整包不超过 50 MB，文件数不超过 5,000 个。
* [ ] 环境变量已保存，并确认不会把敏感信息暴露到浏览器端。