# @gilhrpenner/convex-files-control 中文文档

规范地址：https://npmcn.com/package/%40gilhrpenner/convex-files-control/

版本：0\.6\.0
npm 元数据更新时间：2026-11-08T19:56:08.839Z
中文译文更新时间：2026-11-16T09:00:23.392Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：485 kB，139 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：5 个
- peer 依赖：react ^18\.3\.1 \|\| ^19\.0\.0，convex ^1\.46\.0
- 首次发布：2025-12-29T02:06:55.881Z
- 最新版本发布：2026-11-08T19:56:08.562Z
- 近 30 天下载量：54049（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

Convex 的一个对流文件控制组件.

## 安装

```sh
npm install @gilhrpenner/convex-files-control
```

也可以使用：`pnpm add @gilhrpenner/convex-files-control`、`yarn add @gilhrpenner/convex-files-control`、`bun add @gilhrpenner/convex-files-control`

## README

# Convex 文件控制

用于安全文件上传、访问控制、下载授权和 寿命周期清理。 与Convex仓库和Cloudflare R2公司合作,以及使用 一个可选的HTTP上传/下载路由器外加反应上载钩.

**[生活节日](https://convex-files-control-example.pages.dev/)**

## 特征

-   双步上传(已指定 URL) 有访问密钥和可选过期 .
-   可选的HTTP上传/下载路由并带有认证钩.
-   下载最大用途、过期、可选密码和可共享的赠款 链接.
-   基于访问钥匙的授权(用户身份证、租户身份证等).
-   为过期的上传,赠款,和文件建立内部清理.
-   Convex和R2之间传输文件.
-   预签名或HTTP上传的反应钩子.

## 开发和演示

见 [捐款额](https://npmcn.com/package/%40gilhrpenner/convex-files-control/CONTRIBUTING.md) 用于可复制的检查, [实例/README.md](https://npmcn.com/package/%40gilhrpenner/convex-files-control/example/README.md) 用于当地设置,以及 [实例/就业](https://npmcn.com/package/%40gilhrpenner/convex-files-control/example/DEPLOY.md) 用于部署。 现场演示是共享的 有演示用户假冒的沙盒;仅上传可支配测试数据.

## 安装

要求Convex 1.46+和节点 22.12+(建议第24个节点)。 反应 18和19 继续支持.

```bash
npm install @gilhrpenner/convex-files-control
```

## 快开始

### (1) 增加该部分

```ts
// convex.config.ts
import { defineApp } from "convex/server";
import convexFilesControl from "@gilhrpenner/convex-files-control/convex.config";

const app = defineApp();
app.use(convexFilesControl);

export default app;
```

### 2) 在您的应用程序中创建包装功能

构成部分储存出入控制和下载赠款。 您的应用程序应该存储 其自己的文件元数据(名称,所有者等)并强制执行 auth. 下面的包装 镜像示例应用程序 `example/convex/files.ts`。 。 。 .

```ts
// convex/files.ts
import { ConvexError, v } from "convex/values";
import { mutation } from "./_generated/server";
import { components } from "./_generated/api";

export const generateUploadUrl = mutation({
  args: {
    provider: v.union(v.literal("convex"), v.literal("r2")),
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new ConvexError("Unauthorized");

    return await ctx.runMutation(
      components.convexFilesControl.upload.generateUploadUrl,
      {
        provider: args.provider,
        // r2Config: { accountId, accessKeyId, secretAccessKey, bucketName },
      },
    );
  },
});

export const finalizeUpload = mutation({
  args: {
    uploadToken: v.string(),
    storageId: v.string(),
    fileName: v.string(),
    expiresAt: v.optional(v.union(v.null(), v.number())),
    metadata: v.optional(
      v.object({
        size: v.number(),
        sha256: v.string(),
        contentType: v.union(v.string(), v.null()),
      }),
    ),
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new ConvexError("Unauthorized");

    const { fileName, ...componentArgs } = args;
    const result = await ctx.runMutation(
      components.convexFilesControl.upload.finalizeUpload,
      {
        ...componentArgs,
        accessKeys: [identity.subject],
      },
    );

    // Store your own file record (name, owner, etc.) here.
    // await ctx.db.insert("files", { ... });

    return result;
  },
});
```

### 3) 可选的HTTP路线

如果你想的话 `/files/upload` 财务报告和审定财务报表 `/files/download`,将路由器注册到 `convex/http.ts`。访问密钥由您的钩(而不是通过窗体)提供.

```ts
// convex/http.ts
import { httpRouter } from "convex/server";
import { registerRoutes } from "@gilhrpenner/convex-files-control";
import { components } from "./_generated/api";

const http = httpRouter();

registerRoutes(http, components.convexFilesControl, {
  pathPrefix: "files",
  enableUploadRoute: true,

  // Required when enableUploadRoute is true
  checkUploadRequest: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) {
      return new Response(JSON.stringify({ error: "Unauthorized" }), {
        status: 401,
        headers: { "Content-Type": "application/json" },
      });
    }

    return { accessKeys: [identity.subject] };
  },

  // Optional: persist file metadata after a successful HTTP upload
  onUploadComplete: async (ctx, { result, file, formData }) => {
    const fileNameFromForm = formData.get("fileName");
    const fileName =
      typeof fileNameFromForm === "string"
        ? fileNameFromForm
        : ((file as File).name ?? "untitled");
    // await ctx.runMutation(api.files.recordUpload, { ...result, fileName });
  },

  // Optional: provide accessKey for downloads
  checkDownloadRequest: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (identity) return { accessKey: identity.subject };
  },
});

export default http;
```

HTTP 上传要求 `multipart/form-data` 有字段的字段 :

-   `file` (必须)
-   `provider` (可选,"convex" q"r2")
-   `expiresAt` (可选、时间戳或 `null`(中文(简体) )

访问密钥不能通过窗体接受;它们必须来自 `checkUploadRequest`。其他表格字段可在 `onUploadComplete` 通过 `formData`。 。 。 .

有用的路由选项 :

-   `pathPrefix` (默认 : `/files`(中文(简体) )
-   `defaultUploadProvider` (单位:千美元)`\"convex\"` 或者说 `\"r2\"`(中文(简体) )
-   `enableDownloadRoute` (默认 : `true`(中文(简体) )
-   `requireAccessKey` (人数) `checkDownloadRequest` 以返回访问密钥)
-   `passwordHeader` 编号 : `passwordQueryParam` (覆盖或禁用密码输入)
-   `cors` (精确浏览器来源和允许的标题;其他浏览器来源) 实收 `403`(中文(简体) )

```ts
registerRoutes(http, components.convexFilesControl, {
  cors: {
    allowedOrigins: ["https://app.example.com"],
    allowedHeaders: ["Authorization", "Content-Type"],
    allowCredentials: false,
  },
});
```

请求无 `Origin` 标题继续工作。 若为 `cors` 删除 现有允许的CORS行为保持不变.

## 上传文件

### 指定 URL 流量

```ts
// Client-side
const { uploadUrl, uploadToken } = await generateUploadUrl({
  provider: "convex",
});

const uploadResponse = await fetch(uploadUrl, {
  method: "POST",
  body: file,
  headers: { "Content-Type": file.type || "application/octet-stream" },
});

const { storageId } = await uploadResponse.json();

const result = await finalizeUpload({
  uploadToken,
  storageId,
  fileName: file.name,
  expiresAt: Date.now() + 60 * 60 * 1000,
});
```

### 反应钩

```tsx
import { useUploadFile } from "@gilhrpenner/convex-files-control/react";
import { api } from "../convex/_generated/api";

const convexSiteUrl = import.meta.env.VITE_CONVEX_URL.replace(
  ".cloud",
  ".site",
);

const { uploadFile } = useUploadFile(api.files, {
  method: "presigned",
  http: { baseUrl: convexSiteUrl },
});

// Presigned
await uploadFile({ file, provider: "convex" });

// HTTP route
await uploadFile({
  file,
  method: "http",
  provider: "convex",
  http: {
    baseUrl: convexSiteUrl,
    // authToken: useAuthToken() from @convex-dev/auth/react
  },
});
```

`uploadFile` 接受:

-   `file` (必须)
-   `provider` ("convex"" ""r2")
-   `expiresAt` (时间戳或 `null`(中文(简体) )
-   `method` ("签名""http")

## 下载文件

### 创建赠款+构建 URL

```ts
import { buildDownloadUrl } from "@gilhrpenner/convex-files-control";

const grant = await ctx.runMutation(
  components.convexFilesControl.download.createDownloadGrant,
  {
    storageId,
    maxUses: 1,
    expiresAt: Date.now() + 10 * 60 * 1000,
    shareableLink: false,
  },
);

const url = buildDownloadUrl({
  baseUrl: "https://<your-convex-site>",
  downloadToken: grant.downloadToken,
  filename: "report.pdf",
  // pathPrefix: "/files", // Optional if you changed the HTTP route prefix
});
```

访问密钥不放在 URL 中 。 对于私人赠款,通过下列渠道提供: `checkDownloadRequest` (HTTP路线)或通过 `accessKey` 调用时 `consumeDownloadGrantForUrl`。 。 。 .

### 可共享链接

设定 `shareableLink: true` 以允许未经认证的下载(无访问密钥) a. 组织事项 例应用就是这样产生公共链接的. 如果您启用 `requireAccessKey` 在 HTTP 路由中,仍需要共享链接 `checkDownloadRequest` 以返回访问密钥.

### 密码保护赠款

```ts
const grant = await ctx.runMutation(
  components.convexFilesControl.download.createDownloadGrant,
  { storageId, password: "secret-passphrase" },
);
```

要使用密码保护的赠款, 请通过 `password` 改为 `consumeDownloadGrantForUrl`,或通过 `x-download-password` 标题(首选)或 `password` 查询参数。 查询 params可以被泄露到日志中,因此头或POST流比较安全.

## 访问控制查询( C)

访问密钥是常态化的( trimmed) , 必须包含至少一个非空 数值.

-   `accessControl.addAccessKey(storageId, accessKey)`
-   `accessControl.removeAccessKey(storageId, accessKey)`
-   `accessControl.updateFileExpiration(storageId, expiresAt)`
-   `queries.hasAccessKey(storageId, accessKey)`
-   `queries.listAccessKeysPage(storageId, paginationOpts)`
-   `queries.listFilesPage(paginationOpts)`
-   `queries.listFilesByAccessKeyPage(accessKey, paginationOpts)`
-   `queries.listDownloadGrantsPage(paginationOpts)`
-   `queries.getFile({ storageId })`

增殖用途 `{ numItems: number, cursor: string | null }`。 。 。 .

## 清理

使用 `cleanUp.cleanupExpired` 删除已过期的上传、赠款和文件。 这个 例应用将它包裹在突变中,运行在克龙任务中.

```ts
// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();
crons.hourly(
  "cleanup-expired-files",
  { minuteUTC: 0 },
  internal.files.cleanupExpiredFiles,
  {},
);
export default crons;
```

## 服务器侧助手( Files Control)

如果您喜欢围绕组件调用进行类包装, 请使用 `FilesControl`数字 :

```ts
import { FilesControl } from "@gilhrpenner/convex-files-control";
import { components } from "./_generated/api";

const files = new FilesControl(components.convexFilesControl, {
  // r2: { accountId, accessKeyId, secretAccessKey, bucketName, jurisdiction },
});

await files.generateUploadUrl(ctx, { provider: "convex" });
```

`FilesControl.clientApi()` 还返回一个准备导出 API 表面 如果您想要组件生成您的 Convex 变异和 询问您.

## R2配置

使用 R2 进行上传、下载、删除或删除时提供 R2 证书 转让。 你可以通过 `r2Config` 给组件调用或提供env vars hTTP 路线 :

-   `R2_ACCOUNT_ID`
-   `R2_ACCESS_KEY_ID`
-   `R2_SECRET_ACCESS_KEY`
-   `R2_BUCKET_NAME`
-   `R2_JURISDICTION` (例如可选) `eu` 或者说 `fedramp`(中文(简体) )

设定 `R2_JURISDICTION` 只有用 Cloudflare R2 创建了您的桶 管辖权。 见"云花" [数据位置](https://developers.cloudflare.com/r2/reference/data-location/#using-jurisdictions-with-the-s3-api) 用于支持的管辖权值和S3端点格式.

## 供应商之间的转让

```ts
const result = await ctx.runAction(
  components.convexFilesControl.transfer.transferFile,
  { storageId, targetProvider: "r2", r2Config },
);
```

转移保存访问密钥和下载授权,更新文件记录, 并删除原始存储对象.

## 测试助手

```ts
import { convexTest } from "convex-test";
import { register } from "@gilhrpenner/convex-files-control/test";

const t = convexTest(schema, modules);
register(t, "convexFilesControl");
```

## 示例应用程序

**[生活节日](https://convex-files-control-example.pages.dev/)**

一个完整的 Convex + React + Convex Auth 执行位于 `example/`。 显示:

-   预签名和 HTTP 上传
-   认证下载和共享链接
-   访问密钥管理
-   convex 和 R2 之间的转移
-   预定清理

## 常见问题

### @gilhrpenner/convex-files-control 是什么？

Convex 的一个对流文件控制组件\.

### 如何安装 @gilhrpenner/convex-files-control？

在项目目录运行 npm install @gilhrpenner/convex-files-control，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.3\.1 \|\| ^19\.0\.0）、convex（^1\.46\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gilhrpenner/convex-files-control 支持 TypeScript 吗？

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

### @gilhrpenner/convex-files-control 支持 ESM 还是 CommonJS？

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

### @gilhrpenner/convex-files-control 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gilhrpenner/convex-files-control 可以商用吗？

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

### @gilhrpenner/convex-files-control 的下载量有多少？

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

### @gilhrpenner/convex-files-control 还在维护吗？

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

