# @zakatop/fastsw 中文文档

规范地址：https://npmcn.com/package/%40zakatop/fastsw/

版本：1\.0\.0
npm 元数据更新时间：2026-11-02T22:59:18.306Z
中文译文更新时间：2026-11-02T23:58:00.509Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40zakatop/fastsw
原文对照：https://npmcn.com/package/%40zakatop/fastsw/?lang=original

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

- 包体积（解压后）：4.8 MB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-11-02T22:03:59.669Z
- 最新版本发布：2026-11-02T22:59:18.143Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

非常快的service worker驱动的web代理

## 安装

```sh
npm install @zakatop/fastsw
```

也可以使用：`pnpm add @zakatop/fastsw`、`yarn add @zakatop/fastsw`、`bun add @zakatop/fastsw`

## README

# FastSW

service-worker web代理。获取页面的方法是 [libcurl.js](https://github.com/ading2210/libcurl.js) 在一个 [卷成一捆](https://github.com/MercuryWorkshop/wisp-protocol) 服务器，重写（HTML， CSS和JS）通过嵌入 [橡子](https://github.com/acornjs/acorn) AST pass)，并从service worker传递回浏览器。

-   在页面中加载一个文件(`fastsw.min.js`),加上 `libcurl_full.js` 在它旁边
-   `Fastsw.createFrame()` 将代理页面放入 `<iframe>` 你控制
-   `location` / `top` / `parent` 在代理页面中被替换，因此它们无法导航或破坏框架
-   cookie、存储、IndexedDB和 `postMessage` 每个代理站点保持独立

## 快速启动

### 1\. 提供文件

```js
// server.js
import express from "express";
import { fastswPath } from "fastsw";

const app = express();
app.use("/fastsw/", express.static(fastswPath)); // fastsw.min.js, fastsw.all.js, libcurl_full.js
app.use(express.static("public"));               // your own frontend
app.listen(3000);
```

```sh
npm i ./fastsw-1.0.0.tgz express
node server.js
```

`require("fastsw")` 作品。任何静态主机都可以工作，只要这三个文件最终在一个文件夹中(参见 [事物生活的地方](https://npmcn.com/package/%40zakatop/fastsw/#readme-where-things-live)）。

### 2\. 添加前端

```html
<!-- public/index.html -->
<form id="form"><input id="url" placeholder="Search or enter a URL"><button>Go</button></form>
<div id="view" style="height:90vh"></div>

<script src="/fastsw/fastsw.min.js"></script>
<script>
  const frame = Fastsw.createFrame({ container: document.getElementById("view") });
  document.getElementById("form").onsubmit = (e) => {
    e.preventDefault();
    frame.go(document.getElementById("url").value);
  };
</script>
```

`createFrame` 为你注册service worker。看到 `example__frontend.html` 的完整页面 后退/前进/重新加载按钮。

### 3\. 将它指向一个小精灵服务器

中设置了默认值 `CONFIG` 对象的顶部 `fastsw.all.js` （`wisp: "wss://…/wisp/"`）. 把它设为你自己的 小服务器，还是要 `null` 使用 `/wisp/` 在同一个主机上。

## API

所有这些都将继续存在 `window.Fastsw`.

### `Fastsw.createFrame(arg?, options?)` → `Frame`

`arg` 可以是URL或搜索文本，一个现有的 `<iframe>`，或一个options对象。

| 选项 | 意义 |
| --- | --- |
| `url` | 页面要直接打开 |
| `frame` | 使用这个 `<iframe>` 而不是创造一个 |
| `container` | 元素将新iframe附加到其上 |
| `search` | 用于非URL输入的搜索URL； `%s` 是查询（DuckDuckGo） |
| `attrs` | iframe的额外属性 |
| `className`， `style` | 应用于iframe |

```js
const f = Fastsw.createFrame("https://example.com", { container: document.body });

f.go("wikipedia.org");   // URL, bare domain, or search text
f.back();  f.forward();  f.reload();
f.url;                   // the REAL address of the page shown, never /fastsw/service/...
f.title;
f.ready;                 // promise: service worker registered and active
f.element;               // the <iframe>
f.destroy();

f.addEventListener("navigate",  (e) => console.log(e.detail.url)); // every load
f.addEventListener("urlchange", (e) => console.log(e.detail.url)); // also pushState / hash changes
```

### 其他的助手

| 呼叫 | 它是做什么的 |
| --- | --- |
| `Fastsw.register({ scope })` | 注册服务工作者；通过注册进行解析 |
| `Fastsw.go(input, opts)` | 导航到当前窗口(或 `opts.target`)转到代理页面 |
| `Fastsw.encode(url)` | 这个 `/fastsw/service/<url>` URL格式 |
| `Fastsw.Frame` | 后面的课 `createFrame` |
| `Fastsw.CONFIG` | 活动配置（实际为只读） |

## 事物生活的地方

所有东西都是从那个文件夹里算出来的 `fastsw.*.js` ，因此您可以将它安装在任何地方。 在 `/fastsw/`：

| 事情 | URL |
| --- | --- |
| 服务工作者范围 | `/fastsw/` |
| 代理页面 | `/fastsw/service/<url>` |
| 页内运行时 | `/fastsw/client.js` |
| libcurl(静态) | `/fastsw/libcurl_full.js` |
| 调试页面 | `/fastsw/debug` |

service worker只能声明位于或低于自己脚本文件夹的作用域，这就是FastSW从不注册的原因 `/`。如果将文件夹挂载到未调用的位置 `fastsw` (说 `/static/`),一个 `fastsw/` 添加文件夹 下面是：范围 `/static/fastsw/`， libcurl将留在脚本的旁边 `/static/libcurl_full.js`.

想要完整的 `/` 范围?发送 `Service-Worker-Allowed: /` 为脚本和电话 `Fastsw.register({ scope: "/" })`.

## 配置

`CONFIG` 坐在顶端 `fastsw.all.js`：

| 关键 | 默认的 | 笔记 |
| --- | --- | --- |
| `wisp` | `wss://zakaon.top/wisp/` | 你的小精灵服务器； `null` =同一主机； `/wisp/` |
| `libcurlJS` | `<script folder>/libcurl_full.js` | 静态文件;将它设置为在其他地方托管libcurl |
| `pageWebSocket` | `true` | 发送页面 `WebSocket`也是通过小精灵 |
| `bypass` | `[]` | 工作线程在自己主机上的路径永远不能触及 |
| `scope`， `prefix`， `clientPath`， `debugPath` | 派生的 | 改变 `scope` 通过 `Fastsw.register`，其余的跟着文件夹走 |

## 故障排除

**`Failed to register a ServiceWorker … not under the max scope allowed`**：脚本的文件夹不包含 你要的范围。不通过 `scope: "/"` 除非主机发送 `Service-Worker-Allowed: /`.

**“FastSW无法加载/…/libcurl\_full.js”**文件不在脚本旁边。直接打开那个URL；它应该 下载大约2mb的JavaScript，而不是HTML页面。然后注销该worker并重新加载。

**页上有什么东西断掉了。** 两个工具:

-   开放 `/fastsw/debug` 在代理源上查找工作器最近的请求(报头、状态、cookie `?f=<text>` 过滤)。秘密是保密的。
-   `localStorage.__fastswDebug = "1"` 并重新加载，以便从代理页面内部进行额外的控制台日志记录。

WebSocket生命周期总是被记录为 `[fastsw] websocket …` 行，包括libcurl错误码 握手失败。

## 文件

| 文件 | 目的 |
| --- | --- |
| `dist/fastsw.js` | 所有东西，最小化（加载这个） |
| `dist/fastsw.all.js` | 同样的，可读 |
| `dist/libcurl_full.js` | libcurl.js与它的WASM捆绑在一起 |
| `fastsw.helper.js` / `.cjs` | `fastswPath` 用于Node， ESM和CommonJS |

## 常见问题

### @zakatop/fastsw 是什么？

非常快的service worker驱动的web代理

### 如何安装 @zakatop/fastsw？

在项目目录运行 npm install @zakatop/fastsw，或使用 pnpm add / yarn add / bun add。

### @zakatop/fastsw 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/zakatop\_\_fastsw 是否存在。

### @zakatop/fastsw 支持 ESM 还是 CommonJS？

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

### @zakatop/fastsw 可以商用吗？

@zakatop/fastsw 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @zakatop/fastsw 还在维护吗？

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