# @convex-dev/static-hosting 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/static-hosting/

版本：0\.2\.1
npm 元数据更新时间：2026-10-07T00:51:54.041Z
中文译文更新时间：2026-11-10T17:52:06.953Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40convex-dev/static-hosting
原文对照：https://npmcn.com/package/%40convex-dev/static-hosting/?lang=original
项目主页：https://github.com/get-convex/static-hosting#readme
源码仓库：https://github.com/get-convex/static-hosting

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：514 kB，121 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.3\.1 \|\| ^19\.0\.0，convex ^1\.37\.0
- 首次发布：2026-02-27T16:37:20.378Z
- 最新版本发布：2026-07-28T17:51:12.910Z
- 近 30 天下载量：74798（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Convex 的静态主机组件 .

## 安装

```sh
npm install @convex-dev/static-hosting
```

也可以使用：`pnpm add @convex-dev/static-hosting`、`yarn add @convex-dev/static-hosting`、`bun add @convex-dev/static-hosting`

## README

# Convex 静态主机

[![npm version](https://badge.fury.io/js/@convex-dev%2Fstatic-hosting.svg)](https://badge.fury.io/js/@convex-dev/static-hosting)

直接在 Convex 上托管静态React/Vite 应用程序的 Convex 组件: 否 单独的托管供应商,没有DNS来电,没有第二个部署目标. 运行一个 命令,您的前端为 `https://<deployment>.convex.site` 与你的后端.

## 特征

-   🚀 **部署一个命令 :** 构建、 推后端并上传静态文件 单步.
-   🔄 **SPA 路线 :** 没有扩展的路径返回到 `index.html`。 。 。 .
-   ⚡ **智能缓存 :** 静态文件为速度缓存, 安全更新当 部署了一个新的版本.
-   🔔 **最新部署通知:** 显示连接的用户当 a 新版本已经准备好.
-   🔒 **认证上传 :** 上传通过 Convex CLI 已认证会话; 没有公开上传端点 .
-   🧹 **自动清理 :** 先前0.2.x部署的文件为垃圾 每次部署都收集到 移民指南涵盖一次性v1清理.

[https://github.com/user-attachments/assets/5eaf781f-87da-4292-9f96-38070c86cd39 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/user-attachments/assets/5eaf781f-87da-4292-9f96-38070c86cd39)

[![Share your slop with the Static Hosting Component!](https://thumbs.video-to-markdown.com/d5a10c30.jpg)](https://youtu.be/RNjTys_2OX4)

## 快速启动

> **升级现有的0.1.x应用程序?** 这不是只更新软件包 。 点 您的编码代理 [0.1.x至0.2.x 移徙指南](https://npmcn.com/package/%40convex-dev/static-hosting/MIGRATION.md) 在它改变任何事情之前。 指南涵盖了破旧的再装入, 保存认证和 Webhook URL, 历史 v1 blob 审计, 部署 排序和核查.

```bash
npm install @convex-dev/static-hosting
npx @convex-dev/static-hosting setup
```

对于新设置,命令将组件添加到 `convex/convex.config.ts` 财务报告和审定财务报表 创建一个 `deploy` 脚本在 `package.json`。它不覆盖已有的 曲线配置或 `deploy` 剧本. 完成任何手工编辑 命令,并确认 `npm run deploy` 运行前引用此软件包 :

```bash
npm run deploy
```

你的应用程序是现场直播 `https://<deployment>.convex.site`。 。 。 .

## 设置

### 1\. 安装

```bash
npm install @convex-dev/static-hosting
```

### 2\. 登记构成部分

`convex/convex.config.ts`数字 :

```ts
import { defineApp } from "convex/server";
import staticHosting from "@convex-dev/static-hosting/convex.config";

// Your own HTTP endpoints (convex/http.ts) are served under /api so the
// static site can own the root.
const app = defineApp({ httpPrefix: "/api" });
app.use(staticHosting, { httpPrefix: "/" });

export default app;
```

这是最快的服务模式。 组件拥有 `/`,而你的应用程序 `convex/http.ts` 移动路线 `/api/...`。 。 。 .

如果已有的回调或认证路径必须停留在根上, 请使用 [应用自主根路由](https://npmcn.com/package/%40convex-dev/static-hosting/#readme-keep-existing-http-routes-at-the-root)。作为东道主 在子路径下,见 [在子路径下上山](https://npmcn.com/package/%40convex-dev/static-hosting/#readme-mounting-under-a-sub-path)。 。 。 .

### 3\. 添加部署脚本

```json
{
  "scripts": {
    "deploy": "npx @convex-dev/static-hosting deploy"
  }
}
```

就是这样.

### 将已有的 HTTP 路径保留在根上

不要仅仅为了添加静态托管而移动稳定的webhook, auth, 或 API URL. 离开 组件的 HTTP 路径已卸载, 并记录您的静态齐全 已存在的路由器.

`convex/convex.config.ts`数字 :

```ts
import { defineApp } from "convex/server";
import staticHosting from "@convex-dev/static-hosting/convex.config";

const app = defineApp();
app.use(staticHosting); // no httpPrefix

export default app;
```

`convex/http.ts`数字 :

```ts
import { httpRouter } from "convex/server";
import { registerStaticRoutes } from "@convex-dev/static-hosting";
import { components } from "./_generated/api";

const http = httpRouter();

// Register exact app routes first. Existing auth/webhook helpers can stay here.
// auth.addHttpRoutes(http);
registerStaticRoutes(http, components.staticHosting);

export default http;
```

精准的路由战胜了静态的call-all-,因此已存在的URL继续工作. 这个 组件仍然拥有上传、部署状态和文件存储。 此模式添加 内部查询和存储在未标记的请求中获取,所以倾向于 当您不需要 root- level app 路由时, 组件自有模式.

### 使用非 Vite 捆绑器

这个 `deploy` 步骤和 `upload --build` 设定 `VITE_CONVEX_URL`组合器 使用不同的环境变量常规,将您的构建脚本包成 通过值 :

**对于博览会:**

```json
{
  "scripts": {
    "build": "EXPO_PUBLIC_CONVEX_URL=${VITE_CONVEX_URL:-$EXPO_PUBLIC_CONVEX_URL} npx expo export --platform web"
  }
}
```

**下一个.js:**

```json
{
  "scripts": {
    "build": "NEXT_PUBLIC_CONVEX_URL=${VITE_CONVEX_URL:-$NEXT_PUBLIC_CONVEX_URL} next build"
  }
}
```

模式 `${VITE_CONVEX_URL:-$VAR}` 用途 `VITE_CONVEX_URL` 如果 CLI 设置 否则就回到你的组合变量 这保持了两个 CLI驱动的建设和独立 `npm run build` 工作时.

## 部署

使用单一命令部署 Convex 后端和静态文件 :

```bash
npx convex login           # first time only
npx @convex-dev/static-hosting deploy
```

这个 `deploy` 命令 :

1.  与制作建立前端 `VITE_CONVEX_URL`。 。 。 .
2.  部署Convex后端.
3.  上传 `dist/` 到康维克斯.

为了获得更多的控制,可以分别运行两个半个:

```bash
npx convex deploy
npx @convex-dev/static-hosting upload --build --prod
```

你的应用程序是现场直播 `https://<deployment>.convex.site`。 。 。 .

## 发展工作流程

开发期间使用您的普通前端 Dev 服务器 :

```bash
# Terminal 1
npx convex dev

# Terminal 2
npm run dev
```

对于Vite,这保持了HMR和快速的本地反馈. 静态托管是部署 目标,不是替换dev服务器。 上传每次编辑到开发 部署速度较慢,并丢失了HMR,即使代理写入了大部分代码. 人类仍需要快速循环的视觉检查 瞬间UI状态 调试中.

在发布前,对开发部署进行一次烟雾测试:

```bash
npx @convex-dev/static-hosting upload --build
```

然后使用 `deploy` 用于生产。 这个分块保持了 dev 循环的快度, 但仍然 在运输前测试真正的HTTP,缓存,基道和SPA行为.

## CLI 选项

```bash
npx @convex-dev/static-hosting deploy [options]
  -d, --dist <path>         Path to dist directory (default: ./dist)
  -c, --component <name>    Component instance name (default: staticHosting)
      --skip-build          Skip the build step (use existing dist)
      --skip-convex         Skip Convex backend deployment
      --build-command <cmd> Build command to run (default: 'npm run build')
      --no-spa              Disable SPA fallback (404 instead of /index.html)
      --spa                 Enable SPA fallback (default)
      --cdn                 Use the legacy convex-fs integration
      --cdn-delete-function Legacy app function that deletes CDN blobs

npx @convex-dev/static-hosting upload [options]
  -d, --dist <path>         Path to dist directory (default: ./dist)
  -c, --component <name>    Component instance name (default: staticHosting)
      --prod                Deploy to production deployment
  -b, --build               Run 'npm run build' with VITE_CONVEX_URL set
      --build-command <cmd> Override the build command; implies --build
      --no-spa              Disable SPA fallback (404 instead of /index.html)
      --spa                 Enable SPA fallback (default)
      --cdn                 Use the legacy convex-fs integration
      --cdn-delete-function Legacy app function that deletes CDN blobs
  -j, --concurrency <n>     Parallel upload workers (default: 5)
```

每次上传都是在解剖学上公布的,所以访问者从没有看到提到过的页面 尚未提供的资产。 上传失败离开上一个部署 现场直播 旧文件被安全清理 见 [一体化.md](https://npmcn.com/package/%40convex-dev/static-hosting/INTEGRATION.md) 用于上传限制和生命周期细节.

Convex HTTP 路由目前支持GET,但不是HEAD. 配置时间检查 轻量级请求而不是头部请求.

如果将组件以不同名称挂载,则 `app.use(staticHosting, { name: "custom" })`,通过 `--component custom` 财务报告和审定财务报表 替换每个生成 `components.staticHosting` 参考文献 `components.custom`。 。 。 .

不使用 `--cdn` 为了新的融合。 它瞄准一个更古老的 ConvexFS HTTP API 并仅用于现有部署。 遗留的 CDN 用户必须保留 应用自有根路由因 `/fs/upload` 财务报告和审定财务报表 `/fs/blobs/*` 是根应用程序 路线。 见 `INTEGRATION.md` 用于当前限制.

## 警卫

上传 API 使用 **内部职能** 在组件中只能是 通过:

-   `npx convex run` (需要 Convex CLI 认证)
-   构成部分中的其他对流功能(仅服务器侧)

这意味着未经授权的用户 **无法** 上传文件到您的网站, 即使它们 了解您的 Convex URL .

## 部署后重新装入提示( 可选)

如果你想要一个能促使用户在新部署舰艇时重新装入的横幅, 在您的应用程序中显示部署查询并跳入 `<UpdateBanner />`数字 :

`convex/staticHosting.ts`数字 :

```ts
import { exposeDeploymentQuery } from "@convex-dev/static-hosting";
import { components } from "./_generated/api";

export const { getCurrentDeployment } = exposeDeploymentQuery(
  components.staticHosting,
);
```

`src/App.tsx`数字 :

```tsx
import { UpdateBanner } from "@convex-dev/static-hosting/react";

function App() {
  return (
    <>
      <UpdateBanner message="New version!" buttonText="Reload" />
      {/* ... */}
    </>
  );
}
```

`UpdateBanner` 决定 `api.staticHosting.getCurrentDeployment` 自动. 如果您在不同的模块名下再导出查询,请明确通过:

```tsx
import { api } from "../convex/_generated/api";
<UpdateBanner getCurrentDeployment={api.myModule.getCurrentDeployment} />;
```

对于自定义 UI,请使用钩:

```tsx
import { useDeploymentUpdates } from "@convex-dev/static-hosting/react";

const { updateAvailable, reload, dismiss } = useDeploymentUpdates();
```

## 在子路径下上山

如果根部有其它路线,则将静态站点挂入子路径:

```ts
app.use(staticHosting, { httpPrefix: "/app/" });
```

您还需要告诉你的捆绑者关于基础路径, 所以释放的 HTML 引用正确的 URL。 CLI设定 `STATIC_HOSTING_BASE_PATH` 环境 var 匹配组件运行时的挂载, 所以 `vite.config.ts` 能够 直接读取:

```ts
import { defineConfig } from "vite";

export default defineConfig({
  base: process.env.STATIC_HOSTING_BASE_PATH ?? "/",
});
```

根挂载的应用程序不需要这个; 默认是 `/`。用于网页包装 `publicPath`,用于下一个.js `assetPrefix`。 。 。 .

## SPA 路线

默认情况下,请求一个没有文件扩展名的路径与 上传文件返回到 `index.html`,所以客户端路线喜欢 `/dashboard/settings` 重新装入的工作。 对于未知路径的多页应用程序 应该是一个真正的404,部署与 `--no-spa`数字 :

```bash
npx @convex-dev/static-hosting deploy --no-spa
```

装置是随部署而储存的,所以它用你运送的密码行走 而不是生活在单独的地道里 请求带有扩展名的路径 (例如:. `/missing.js`总是在找不到时404, 不论设置如何 .

## 从0.1.x升级

0.2.0 将上传和文件存储移入组件. 你必须移除 `exposeUploadApi` 从 `convex/staticHosting.ts` 财务报告和审定财务报表 **调用您的 资产** 因为0.1.x文件存在于应用程序的存储中. 抓住两个 当前 v1 显示和更广泛的应用存储目录 : 上传时间较长 v1 可能留下了静态块,当前清单不再列出.

然后可以选择两种服务模式:

-   如果静态网站可以拥有 `/`,将组件挂起,去掉旧的 `registerStaticRoutes` 电话.
-   如果已有的 HTTP 路由必须停留在 `/`,保留 `convex/http.ts` 联 合 国 `registerStaticRoutes` 电话 0.2执行部分读取了新的 组件自有文件,而不改变这些路由 URL.

见奉献 [0.1.x至0.2.x 移徙指南](https://npmcn.com/package/%40convex-dev/static-hosting/MIGRATION.md) 准确 步骤、核查、回滚和可选的分阶段切入.

## 如何运作

1.  **构建 :** 您的捆绑器释放 `dist/`。 。 。 .
2.  **上传 :** cLI 使用您认证的 Convex 会话生成签名 上传 URL,将文件推向 Convex 存储,记录元数据,以及 GC 旧 部署.
3.  **服务:** hTTP 动作查看请求的路径, 将文件流到 右边 `Content-Type`,对散装资产适用长期缓存,以及 倒计时 `index.html` 用于SPA路线.

## 示例

见 [`example/`](https://npmcn.com/package/%40convex-dev/static-hosting/example) 用于一个完整的Vite + React app.

```bash
npm install
npm run dev
```

## 捐款

见 [捐款额](https://npmcn.com/package/%40convex-dev/static-hosting/CONTRIBUTING.md)。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @convex-dev/static-hosting 是什么？

Convex 的静态主机组件 \.

### 如何安装 @convex-dev/static-hosting？

在项目目录运行 npm install @convex-dev/static-hosting，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.3\.1 \|\| ^19\.0\.0）、convex（^1\.37\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 static-hosting，可以用 npx static-hosting 直接运行。

### @convex-dev/static-hosting 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @convex-dev/static-hosting 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @convex-dev/static-hosting 可以商用吗？

@convex-dev/static-hosting 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @convex-dev/static-hosting 的下载量有多少？

根据 npm 官方下载统计，@convex-dev/static-hosting 在 2026/10/11 – 2026/11/09 这 30 天内被下载 74,798 次，日均约 2,493 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @convex-dev/static-hosting 还在维护吗？

最新版本 0\.2\.1 发布于 2026/07/29（3 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/02/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。