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

# Static Hosting

> Publish built static websites to the StepFun Open Platform and manage previews and live versions

Static Hosting lets you publish a built static website to the StepFun Open Platform and generate preview links that you can share with others. You do not need to prepare a server or configure a CDN. After uploading your website files, you can preview the site, launch it, and manage its versions.

This guide is for users of the **My Sites** feature on the StepFun Open Platform. It covers the workflow from the first deployment through ongoing operations.

<Note>
  To deploy and manage sites through the CLI, CI/CD, or MCP, see [Static Hosting CLI & MCP](/docs/en/guides/developer/static-hosting-cli-mcp).
</Note>

## Use cases

* Product websites, campaign pages, help centers, portfolios, and other static websites.
* Build outputs generated by React, Vue, Vite, or static exports from Next.js.
* Workflows that need shareable previews before launch or multiple versions that can be rolled back.

Static Hosting only distributes static files and does not provide a server runtime. Server-side code such as PHP, Python, and Node.js is not executed in the hosting environment.

## Core concepts

| Concept      | Description                                                                                                                                     |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Site         | An independent website project with a name, URL, serving mode, and multiple versions.                                                           |
| Version      | A snapshot of files created by a deployment, incremented as `v1`, `v2`, and so on. Versions can be previewed, launched, or rolled back.         |
| Preview link | A temporary shareable link for a specific version. Previewing does not change the live version. The link can have an expiry time or be revoked. |
| Live version | The version currently served to external visitors. A site has only one live version at a time.                                                  |
| Root page    | The file returned when visitors access the site root path `/`, usually `index.html`.                                                            |

## Quick start

### 1. Open My Sites

Sign in to the [StepFun Open Platform](https://platform.stepfun.ai), open **My Sites** from the console sidebar, and click **New Site**.

The site list supports name search and filtering by **All**, **Live**, **Draft**, and **Error**.

### 2. Prepare and upload website files

In the **Publish Site** window, enter a site title and upload any of the following by dragging them into the upload area or selecting them with the file picker:

* A single `.zip` archive
* A website folder
* Multiple website files

When you upload a folder, the system automatically removes the outermost common directory. For example, if you select the `dist/` folder, `dist/index.html` is published as `index.html`.

### 3. Confirm the root page

If the uploaded content contains `index.html` at its root, the system automatically uses it as the root page.

If there is no `index.html`, the system lists the available options:

* Select an HTML file to return it when visitors access `/`.
* Select **No root page** to return 404 at `/`.

When you upload a ZIP archive, you cannot select its root page in the upload window. Put `index.html` at the archive root. The deployment fails if the archive does not contain this file.

### 4. Generate a preview and launch

Click **Publish**. The system uploads the files, processes the version, and generates a preview link. When the deployment is ready:

1. Click **Open Preview** and check that the page and its resources work correctly.
2. Find the version in version history and click **Launch**.
3. Confirm the operation. The selected version replaces the current live version.

The first deployment generates a preview only and does not automatically replace the live version. The live URL appears on the site details page and site card after the first launch.

## Upload requirements and limits

### File size and count

* The total size of a deployment must not exceed **50 MB**.
* A deployment must not contain more than **5,000 files**.
* A site name can contain up to **64 characters**.
* The maximum number of saved versions depends on your account quota. If the product indicates that the limit has been reached, delete older versions first.

The `.zip` limit is checked against the archive size. The server checks file types and paths again after extracting the archive.

### Supported file types

Common supported types include:

`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`.

The following types are explicitly prohibited:

`php`, `py`, `exe`, `sh`, `bat`, `cmd`, `dll`, `so`, `jsp`, `asp`, `aspx`, `cgi`, `pl`.

Files with extensions outside the supported list are rejected. We recommend uploading a `dist` or `build` directory generated by your build tool instead of source code, dependency directories such as `node_modules`, or server-side files.

## Previews, launch, and version management

### Preview links

Each deployment generates a preview link for the new version. Preview links support the following operations:

* Open the link to check the version
* Copy the link and share it with collaborators
* Set an expiry: never, 24 hours, 7 days, or 30 days
* Revoke the link
* Generate a new link after revocation

A preview link points to the selected version and is different from the live URL. A revoked link immediately returns 404. A link with an expiry also becomes unavailable after it expires.

### Launch

On the site details page, open the operation menu for a version under **Version History** and click **Launch**. A confirmation prompt appears because launching replaces the current live version.

Only versions that are not already live and have not been rejected by review can be submitted for launch. The final result is determined by server-side validation. Versions rejected by review or with invalid configuration cannot be launched.

### Roll back

If a new version has a problem, find an earlier version under **Version History**, open its operation menu, and click **Roll Back**. After confirmation, the selected version becomes live and the previous live version remains in history.

### Republish

The **Republish** action in the upper-right corner of the site details page has two uses:

* **Without new files**: Reactivate the current live version, for example when the live URL is unavailable or you need to trigger the launch process again.
* **With new files**: Create a new version. The new version first generates a preview and can be launched after review.

If you change environment variables, upload and publish a new build output. Relaunching an old version does not apply the latest environment variables.

## Serving modes

In **Site Settings**, choose a serving mode:

* **SPA**: Unknown routes return the root page, usually `index.html`. Use this for client-side routers such as React Router and Vue Router. Refreshing a route such as `/about` lets the frontend application handle the route.
* **Static**: Missing files return 404. Use this when each URL should map to an existing file in a regular static website.

Changing the serving mode takes effect immediately. Use SPA for client-side routing and Static when missing paths should return an explicit 404.

## Custom response headers

Put `page.config.json` in the **root directory** of the uploaded package to configure response headers for different paths:

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

| Field   | Description                                        |
| ------- | -------------------------------------------------- |
| `path`  | The path pattern, such as `/*` or `/assets/*`.     |
| `name`  | The response header name, such as `Cache-Control`. |
| `value` | The response header value.                         |

After deployment, view the parsed rules for the live version in the **Response Header Rules** tab. This tab is read-only. To change the rules, update `page.config.json` and publish a new version. A version with invalid configuration is marked as rejected and cannot be launched.

## Build-time environment variables

### Configure variables

In **Site Settings**, add variables under **Environment Variables**. Variable names must:

* Start with an uppercase English letter
* Contain only uppercase English letters, numbers, and underscores, such as `API_BASE_URL`
* Be unique within a site

You can configure up to 50 variables per site. Each value must be a single line containing no more than 2,048 characters.

### Reference variables in files

Use the <code>{'{{PAGE_ENV:VARIABLE_NAME}}'}</code> placeholder in static files. For example:

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

During the deployment build, the system replaces placeholders in text files. The current text file types include `.html`, `.htm`, `.js`, `.css`, `.json`, `.txt`, `.svg`, and `.xml`. Images, fonts, audio, video, and PDF files are not modified. Undefined placeholders remain unchanged.

Environment variables are injected at deployment build time. Saving a variable does not rewrite already published versions. After changing a variable, upload and publish a new build output. Republishing an old version does not inject the latest value.

Do not put passwords, private keys, long-lived access tokens, or other highly sensitive information in frontend environment variables. Static files are sent to visitors, and users may be able to inspect the injected values in their browsers.

## Analytics and deployment logs

Open the **Analytics** tab on the site details page to view:

* Request count
* Transferred traffic
* Daily request trends
* Deployment logs, including version, operation, operator, time, and result

Analytics supports `24h`, `7d`, and `30d` ranges. New sites and sites without requests show an empty state. Statistics become available after visitors access the live or preview URL.

## Site settings and deletion

**Site Settings** supports:

* Renaming the site
* Switching between SPA and Static serving modes
* Managing environment variables
* Deleting the site

Deleting a site requires you to enter the full site name in the confirmation dialog. Deletion is permanent and removes the site and all of its versions. The live URL and preview links become invalid. Back up any required versions with the version download feature before deleting the site.

## Frequently asked questions

### `/` returns 404

Check that:

1. `index.html` exists at the root of the uploaded package.
2. If you uploaded files or a folder, the correct root page is selected.
3. The site is not configured with **No root page**.
4. The site is live rather than only having a preview version.

### Refreshing a frontend route returns 404

Switch the site serving mode to SPA and revisit the live URL. Static mode returns only files that actually exist.

### Deployment rejects a file type

Check the file name or extension in the error message. Remove prohibited or unsupported files and publish again. Files inside ZIP archives are checked as well. Make sure the archive does not contain server-side source code or scripts.

### Environment variables are not updated

Environment variables are replaced at build time. Confirm that the variable is saved, upload a new static build output, and publish a new version. Republishing an old version does not inject the variable again.

### A preview link does not open

Check whether the link has expired or been revoked. Generate a new link from the version operation menu. A link cannot be restored after its version or site is deleted.

### A new version cannot be launched

Check the status label on the version. Review rejection, review submission failure, or rejected `page.config.json` configuration can prevent launch. Fix the website or configuration and publish a new version.

## Deployment checklist

* [ ] The entry file and resource paths use relative paths, with matching case.
* [ ] The root directory contains `index.html`, or another root page is explicitly selected.
* [ ] The serving mode matches the application type: SPA or Static.
* [ ] `node_modules`, source code, and unnecessary server-side scripts have been removed.
* [ ] The deployment package is no larger than 50 MB and contains no more than 5,000 files.
* [ ] Environment variables are saved and do not expose sensitive information to browsers.