# @effect-vfs/core 中文文档

规范地址：https://npmcn.com/package/%40effect-vfs/core/

版本：0\.11\.0
npm 元数据更新时间：2026-11-14T12:45:23.742Z
中文译文更新时间：2026-11-14T13:36:09.946Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40effect-vfs/core
原文对照：https://npmcn.com/package/%40effect-vfs/core/?lang=original
项目主页：https://github.com/lloydrichards/effect-virtual-fs#readme
源码仓库：https://github.com/lloydrichards/effect-virtual-fs

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

- 包体积（解压后）：1 MB，141 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：effect ~4\.1\.4
- 首次发布：2026-09-09T10:05:04.393Z
- 最新版本发布：2026-11-14T12:45:23.381Z
- 近 30 天下载量：2034（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

Effect 的运行时中立虚拟文件系统核心 .

## 安装

```sh
npm install @effect-vfs/core
```

也可以使用：`pnpm add @effect-vfs/core`、`yarn add @effect-vfs/core`、`bun add @effect-vfs/core`

## README

# @ effect- vfs/ core (帮助)

`@effect-vfs/core` 使用字节保存路径、有明确权限的呼叫者、配额、, 手表 固定装置 还有手提快照 它不访问主机文件系统 .

需要直接控制共享音量或字节导向路径时使用核心. 对于 Effect 的标准 `FileSystem` 服务, 使用 [`@effect-vfs/memory`](https://npmcn.com/package/%40effect-vfs/memory/README.md)。 。 。 .

该套件执行一个有文件记载的POSIX行为子集. 它没有声称POSIX完全符合规定。 见 [已执行配置文件](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.okf/profiles/implemented-filesystem.md) 精确的许可,路径,时间戳,配额,和原子学规则.

## 安装

```sh
npm install @effect-vfs/core@latest
```

软件包宣布其精确的Effect版本为对等依赖. 卷构造器和快照三角洲函数需要 Effect's `Crypto` 服务。 在节点上安装匹配 供应商和供应 `NodeCrypto.layer` 当运行这些效果时 :

```sh
npm install "@effect/platform-node-shared@$(npm view @effect-vfs/core peerDependencies.effect)"
```

## 创建孤立的工作空间

拥有文件的一卷. 一个呼叫者提供身份,权限,和一个工作目录. 范围控件关闭时 影响范围结束。 这个例子让一个没有特权的调用者访问一个受限卷中的一个目录.

```ts
import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
import { ByteSize, Effect } from "effect"

const utf8 = new TextEncoder()

const program = Effect.scoped(Effect.gen(function*() {
  const volume = yield* Vfs.make({
    maxEntries: 100,
    maxBytes: ByteSize.megabytes(1),
    maxFileBytes: ByteSize.kilobytes(100)
  })

  const admin = yield* volume.caller()
  yield* admin.mkdir("/workspace", { mode: 0o770 })
  yield* admin.chown("/workspace", { uid: 1000, gid: 1000 })

  const developer = yield* volume.caller({
    identity: { uid: 1000, gid: 1000, groups: [], privileged: false },
    umask: 0o027
  })

  yield* developer.writeFile(
    "/workspace/config.json",
    utf8.encode(JSON.stringify({ feature: "preview" })),
    { access: "write", create: "exclusive", mode: 0o666 }
  )

  const file = yield* developer.open("/workspace/config.json", { access: "read" })
  const contents = yield* file.read(100_000)
  const metadata = yield* file.stat

  return {
    config: JSON.parse(new TextDecoder().decode(contents)),
    mode: metadata.mode.toString(8)
  }
}))

const result = await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))
console.log(result) // { config: { feature: "preview" }, mode: "640" }
```

Root caller默认享有特权. 特权是明确的:设置 `uid` 改为 `0` 不给予它。 新建根 调用器默认为 umask `0o022`; 开发商的 `0o027` 掩码会转换请求的文件模式 `0o666` 输入 `0o640`。 。 。 .

根包出口 `VirtualFileSystem` 作为命名空间。 等同的直接模块导入为 `import * as Vfs from "@effect-vfs/core/VirtualFileSystem"`。 。 。 .

## 将调用者绑入目录

`caller.withRoot(path)` 创建一个范围化的呼叫者 `/` 是一个目录。 绝对连锁和 `..` 留下来 入于根内. 重命名根保留访问权限; 删除它会永久使调用者无效 .

保持呼叫者范围开放,仅传递消费者需要的能力. 现有的硬链接可以共享 文件内容横跨根。 见 [关闭工作空间](https://npmcn.com/package/apps/docs/app/content/guides/confined-workspaces.mdx) 以 Effect 的完整示例 `FileSystem` 服务和禁闭限制.

## 指南和参考

-   [固定和快照](https://npmcn.com/package/apps/docs/app/content/guides/fixtures-and-snapshots.mdx) 覆盖被种子的树木,可解码器,以及可移植的三角洲.
-   [重叠工作空间](https://npmcn.com/package/apps/docs/app/content/guides/overlay-filesystems.mdx) 覆盖独立的编辑和 `mergeSnapshotDeltas` 冲突.
-   [快照搜索](https://npmcn.com/package/apps/docs/app/content/guides/snapshot-search.mdx) 覆盖文件名词汇、内容匹配和定界结果.
-   [文件系统模型](https://npmcn.com/package/apps/docs/app/content/concepts/filesystem-model.mdx) 解释呼叫者、 控件、 权限和字节路径 .
-   [API 参考](https://npmcn.com/package/apps/docs/app/content/api/core/virtual-file-system.mdx) 列出构造器、服务和操作.

## 限制

包裹是实验性的. 公共API在小版本之间可能会有变化.

路径保存任意的非 NUL 字节 。 组件被限制在255字节上,而同义链接转录到40个链接. 卷选项绑定条目,文件大小,待定操作,并监视队列. 记忆卷没有提供主机或 崩溃耐久性。 见 [兼容性和限制](https://npmcn.com/package/apps/docs/app/content/reference/compatibility-and-limits.mdx) 整个合同.

## 常见问题

### @effect-vfs/core 是什么？

Effect 的运行时中立虚拟文件系统核心 \.

### 如何安装 @effect-vfs/core？

在项目目录运行 npm install @effect-vfs/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（~4\.1\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @effect-vfs/core 支持 TypeScript 吗？

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

### @effect-vfs/core 支持 ESM 还是 CommonJS？

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

### @effect-vfs/core 可以商用吗？

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

### @effect-vfs/core 的下载量有多少？

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

### @effect-vfs/core 还在维护吗？

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