# @cf-wasm/plugins 中文文档

规范地址：https://npmcn.com/package/%40cf-wasm/plugins/

版本：0\.2\.0
npm 元数据更新时间：2026-08-01T02:29:47.757Z
中文译文更新时间：2026-11-09T08:30:52.526Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cf-wasm/plugins
原文对照：https://npmcn.com/package/%40cf-wasm/plugins/?lang=original
项目主页：https://github.com/fineshopdesign/cf-wasm/tree/main/packages/plugins#readme
源码仓库：https://github.com/fineshopdesign/cf-wasm

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

- 包体积（解压后）：45.8 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：rollup ^4\.0\.0，vite ^6\.1\.0 \|\| ^7\.0\.0
- 首次发布：2025-11-05T20:08:30.406Z
- 最新版本发布：2026-08-01T02:29:47.442Z
- 近 30 天下载量：11679（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 10 个）

## 中文简介

Cf-wasm 插件

## 安装

```sh
npm install @cf-wasm/plugins
```

也可以使用：`pnpm add @cf-wasm/plugins`、`yarn add @cf-wasm/plugins`、`bun add @cf-wasm/plugins`

## README

# @ cf-wasm/ 插件

使Cloudflare工人兼容模块的插件与维特等现代构建工具无缝地工作.

## 云浮模块

Vite 插件导出自 `@cf-wasm/plugins/vite-additional-modules` 亚模块能够正确解决在Cloudflare工人身上得到本土支持的无害环境管理型进口,例如:

-   `.wasm?module`
-   `.wasm`
-   `.txt`
-   `.bin`

这些导入类型通常在标准开发环境中失败,因为它们依赖于Cloudflare的模块加载器行为. 这个插件通过在开发时模拟 Cloudflare 的模块导入系统并构建时间来弥补差距 .

## 为什么你需要它

当使用针对Cloudflare工人的框架或适配器时(例如, `@sveltejs/adapter-cloudflare` 在SvelteKit应用程序中,您可能会遇到构建时的错误,例如:

```
error during build:
[vite:wasm-fallback] Could not load /home/user/svelte-kit-app/src/lib/resvg.wasm (imported by src/routes/resvg/+server.ts): "ESM integration proposal for Wasm" is not supported currently. Use vite-plugin-wasm or other community plugins to handle this. Alternatively, you can use `.wasm?init` or `.wasm?url`. See https://vite.dev/guide/features.html#webassembly for more details.
```

之所以发生这种情况,是因为Vite(以及大多数捆绑者)在本地并不理解Cloudflare的特殊模块查询语法.

这个 `vite-additional-modules` 插件通过教Vite如何处理这些导入来解决这个问题.

## 安装

```shell
npm install @cf-wasm/plugins --save-dev
```

## 使用量

将插件添加到您的 `vite.config.js` (或 `vite.config.ts`:

```ts
// vite.config.{ts|js}
import additionalModules from "@cf-wasm/plugins/vite-additional-modules";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [additionalModules()],
});
```

> \[注\] 如果依赖使用Cloudflare支持的无害环境管理进口语法(例如, `@cf-wasm/satori`),您需要确保 Vite 不外部化 `@cf-wasm/satori` 安全部门改革捆绑过程中的模块:
> 
> ```ts
> // vite.config.{ts|js}
> import additionalModules from "@cf-wasm/plugins/vite-additional-modules";
> import { defineConfig } from "vite";
> 
> export default defineConfig({
>   plugins: [additionalModules()],
>   ssr: {
>     noExternal: [/^@cf-wasm\/.*/],
>   },
> });
> ```

### 示例: SvelteKit + Cloudflare 适应器

使用时 `@sveltejs/adapter-cloudflare`,只需在您的 Vite 配置中包含此插件 :

```ts
// vite.config.{ts|js}
import additionalModules from "@cf-wasm/plugins/vite-additional-modules";
import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [sveltekit(), additionalModules()],
});
```

```js
// svelte.config.js
import adapter from "@sveltejs/adapter-cloudflare";
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";

/** @type {import('@sveltejs/kit').Config} */
const config = {
  // Consult https://svelte.dev/docs/kit/integrations
  // for more information about preprocessors
  preprocess: vitePreprocess(),

  kit: {
    adapter: adapter(),
  },
};

export default config;
```

现在,你可以安全地使用进口,例如:

```ts
// src/routes/api/+server.ts
import wasmModule from "$/lib/my-module.wasm?module";
import textData from "$/lib/my-schema.txt";

export async function GET() {
  //...
}
```

两者在 `development` 并部署到 `Cloudflare Workers`。 。 。 .

## 支持的扩展

| 延长 | 说明 | 输出类型 |
| --- | --- | --- |
| `.wasm?module` | 网络大会模块 | `WebAssembly.Module` |
| `.wasm` | 网络大会模块 | `WebAssembly.Module` |
| `.txt` | 纯文本文件 | `string` |
| `.bin` | 二进制文件 | `ArrayBuffer` |

## 如何运作

-   单位 `development`,插件会截取Vite的模块解析度,并模拟 Cloudflare 的导入行为,根据需要编译或服务文件.
-   单位 `production builds`,插件确保这些文件被正确释放,并作为符合 Cloudflare 工人运行时间的标准的无害环境管理导入物引用.

## 常见问题

### @cf-wasm/plugins 是什么？

Cf-wasm 插件

### 如何安装 @cf-wasm/plugins？

在项目目录运行 npm install @cf-wasm/plugins，或使用 pnpm add / yarn add / bun add。

### @cf-wasm/plugins 支持 TypeScript 吗？

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

### @cf-wasm/plugins 支持 ESM 还是 CommonJS？

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

### @cf-wasm/plugins 可以商用吗？

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

### @cf-wasm/plugins 的下载量有多少？

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

### @cf-wasm/plugins 还在维护吗？

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