---
title: "HTTP 下载"
description: "将 HTTPS 资源安全下载到 Kasumi 虚拟文件系统。"
---


> 将 HTTPS 资源下载到 Kasumi 可写虚拟路径，并控制覆盖、重定向、超时和体积上限。

## 模块边界

`http` 当前只提供下载，不提供任意 HTTP 请求、上传、进度事件或公开的 `AbortSignal`。下载结果
必须写入沙箱，不能返回真实文件路径。

实现入口：

| 入口 | 责任 |
| --- | --- |
| `frontend/src/api/http.ts` | 参数守卫和 120 秒请求超时 |
| `frontend/src/bridge/ksm.ts` | `KSM.http.download` 根入口 |
| `windows/src/platform/ksm_windows_host_services.cpp` | WinHTTP 下载、重定向、取消和临时文件 |
| `android/app/src/main/java/dev/kasumi/app/KSMAndroidHostServices.kt` | `HttpsURLConnection` 下载和生命周期取消 |

## 平台支持

| 方法 | Windows | Android | 权限 |
| --- | --- | --- | --- |
| `KSM.http.download` / `http.download` | 支持 | 支持 | `http.download` |

## 参数与返回

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 是 | 绝对 `https://` URL |
| `path` | string | 是 | `app://data`、`app://cache` 或 `app://tmp` 下的文件路径 |
| `overwrite` | boolean | 否 | 默认 `false` |

返回：

```ts
interface KSMHttpDownloadResult {
  path: string;
  bytes: number;
}
```

`path` 是规范化后的虚拟目标路径，`bytes` 是实际写入字节数。

## 固定行为

- 只允许 HTTPS；拒绝用户名密码、空主机、超长 URL 和非 HTTPS scheme。
- 目标不能是目录、只读根或 `app://picked`，也不能是真实文件路径。
- 最多跟随 5 次重定向，每一跳仍必须是 HTTPS。
- 总超时 120 秒，最大下载体积 100 MiB。
- 下载写入同目录 `.part` 文件；成功后提交，失败、超时或取消时删除临时文件。
- `overwrite` 为 `false` 时，目标已存在返回 `IO_ERROR`，不覆盖原文件。
- 不提供进度事件。前端超时会发送现有 `cancel` 消息，宿主收到后必须中止网络请求。

## 示例

```ts
import { KSM } from '@kasumi/bridge';

try {
  const result = await KSM.http.download({
    url: 'https://example.com/releases/kasumi.zip',
    path: 'app://cache/releases/kasumi.zip',
    overwrite: false
  });

  console.info(result.path, result.bytes);
} catch (error) {
  if (error instanceof Error && error.name === 'IO_ERROR') {
    console.warn('目标已存在或下载提交失败');
  }
}
```

## 错误行为

| 情况 | 错误 |
| --- | --- |
| 非 HTTPS、凭据、空主机、非法 `path`、非布尔 `overwrite` | `INVALID_ARGS` |
| 未授予 `http.download`，或路径越界 | `PERMISSION_DENIED` |
| 目标已存在且未允许覆盖 | `IO_ERROR` |
| 重定向超限、体积超限、网络或提交失败 | `IO_ERROR` |
| 前端请求超时 | `TIMEOUT` |
| 请求被取消 | `CANCELLED` |
| 宿主未配置下载服务 | `NOT_SUPPORTED` |

前端封装会先抛普通 `TypeError` 拒绝明显非法参数；绕过封装直接调用协议时，宿主仍会返回标准
错误码。

## 平台差异

Windows 使用 WinHTTP，取消时关闭活动句柄；Android 使用 `HttpsURLConnection`，取消时
`disconnect()` 活动连接。Android 在 `onTrimMemory` 和 Activity 销毁时也会取消下载。两端都
关闭自动重定向并逐跳校验 HTTPS。

## 排查路径

1. 确认 URL 是绝对 HTTPS，且没有凭据。
2. 确认目标是可写沙箱中的文件，不是目录或 `app://picked`。
3. 确认目标不存在，或显式传入 `overwrite: true`。
4. 检查重定向次数是否超过 5 次，以及每一跳是否仍为 HTTPS。
5. 检查响应体积是否超过 100 MiB，总耗时是否超过 120 秒。
6. 失败后检查目标目录是否残留 `.part` 文件。
7. 页面取消后检查宿主网络连接是否已关闭。