# @ecopages/file-system 中文文档

规范地址：https://npmcn.com/package/%40ecopages/file-system/

版本：0\.7\.1
npm 元数据更新时间：2026-11-12T23:41:22.026Z
中文译文更新时间：2026-11-13T06:05:01.823Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ecopages/file-system
原文对照：https://npmcn.com/package/%40ecopages/file-system/?lang=original
源码仓库：https://github.com/ecopages/ecopages

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

- 包体积（解压后）：97.8 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.22\.0 \|\| \>=26\.0\.0
- 运行依赖：0 个
- 首次发布：2026-03-08T20:13:47.940Z
- 最新版本发布：2026-11-12T23:41:21.350Z
- 近 30 天下载量：4509（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：125（近 12 个月 125 个）

## 中文简介

Ecopage 的节点文件系统工具

## 安装

```sh
npm install @ecopages/file-system
```

也可以使用：`pnpm add @ecopages/file-system`、`yarn add @ecopages/file-system`、`bun add @ecopages/file-system`

## README

# @ epopages/ file- system

Ecopages的运行时文件系统工具。 执行是节点的 `node:fs` 财务报告和审定财务报表 `crypto` 在每次运行,包括Bun.

## 特征

-   **节点执行**数字 : `node:fs/promises.glob()`, (中文(简体) ), `crypto`,以及 `node:fs` 每一次运行.
-   **一个接口**: 导入呼叫站点 `fileSystem` 而不选择适配器。 测试替换为 `installFileSystem` 并可以把它包起来 `createRecordingFileSystem` 以观察每个路径参数.
-   **递归表**数字 : `watch()` 每个最小目录根打开一个本地递归监视器,而不是每个子目录打开一个监视器。 文件与缺失的根共享非复式父手表 。 它在不释放初始变化的情况下索引现有条目,将本地事件合并为50 ms,支持将路径添加到运行中的监视中,并绘制出条形路径回所请求的根.
-   **类型安全**: 完整类型脚本支持并具有一致的API.

## 安装

```bash
bun add @ecopages/file-system
```

## 使用量

```typescript
import { fileSystem } from '@ecopages/file-system';

// Glob files
const files = await fileSystem.glob(['**/*.ts'], { cwd: './src' });

// Read files
const content = await fileSystem.readFile('file.txt');

// Hash files
const hash = fileSystem.hash('file.txt');

// Write files
fileSystem.write('output.txt', 'Hello World');

// Check existence
if (fileSystem.exists('file.txt')) {
    // ...
}

// Watch a tree, skipping dependencies
const watcher = fileSystem.watch(['./src'], {
    ignored: (path) => path.includes('node_modules'),
    onChange: ({ type, path }) => console.log(type, path),
    onError: (error) => console.error(error),
});
await watcher.ready;
await watcher.add(['./generated']);
await watcher.close();
```

`watch()` 报表文件更改为 `add`, (中文(简体) ), `change` 或者说 `unlink`,目录更改为 `addDir` 或者说 `unlinkDir`将现有文件的原子替换报告为 `change`。如果本地事件省略了文件名, `watch()` 调和本地根并可以发出一个 `rescan` ; 消费者应一次使这些根无效。 缺失的根会从其最近的已存在的父端被监视,并在创建后开始报告. `add()` 扩展在新路径下已经存在的运行中的订阅和索引条目,而不报告它们。 如果注册失败, 添加的路径会被回滚, 以便呼叫者可以重试 。 拒绝许可的儿童在索引编制过程中被跳过,因此无障碍的兄弟姐妹仍然受到监视。 使用传递到 `watch()`选项 `ignored` 在对现有子目录内容进行索引之前进行上游运行,因此被忽略的子树不会被扫描. 在Linux上,节点打开了每条递归根的一块不建议使用的手表,使树如 `node_modules` 从成本内核表。 返回时 `true` 没有统计只针对被忽略的路径,因为一个拓宽后方的上游只能对用统计给出的答案这样做. 正在编制索引时删除的目录被视为已消失,而不是错误.

## 路径

`@ecopages/file-system/path` 持有 Ecopages 的路径常规:每条路径都使用向前斜线,一个绝对的Windows路径保持其给定的驱动信件(`D:/app/src/page.tsx`; 使用情况 `path.isWithin` 而不是测试封装的字符串前缀。 其业务镜像 `node:path` (单位:千美元)`join`, (中文(简体) ), `resolve`, (中文(简体) ), `relative`, (中文(简体) ), `dirname`, (中文(简体) ), `basename`, (中文(简体) ), `extname`, (中文(简体) ), `isAbsolute`, (中文(简体) ), `normalize`, (中文(简体) ), `parse`, (中文(简体) ), `format`, (中文(简体) ), `matchesGlob`并总是返回该表。 路径 `fileSystem` 返回,从 `realpath`, (中文(简体) ), `glob`, (中文(简体) ), `readdir`, (中文(简体) ), `readlink`, (中文(简体) ), `mkdtemp`, (中文(简体) ), `tempDir` 财务报告和审定财务报表 `watch`里面也一样.

```typescript
import { path } from '@ecopages/file-system/path';

const page = path.join(rootDir, 'src', 'pages', 'index.tsx');
const here = path.fromFileUrl(import.meta.url);
const module = await import(path.toFileUrl(page).href);
```

| 导出 | 说明 |
| :-- | :-- |
| `path.cwd()` | 工作目录,以这种形式 |
| `path.isWithin(directory, file)` | 是否为 `file` 实值 `directory` 或从下面 |
| `path.fromNative(path)` | 转换本地路径, 如 `import.meta.dirname` |
| `path.toNative(path)` | 转换为 Windows 上的回鞭, 用于需要它们的工具 |
| `path.fromFileUrl(url)` | 转换 a `file:` 路径的 URL |
| `path.toFileUrl(path)` | 将路径转换为 `file:` URL,作为 `import()` 窗口上的需求 |
| `createPath('posix' | 'win32')` | 一个主机口味的相同操作, 用于测试 |

## API 密码

| 方法 | 说明 |
| :-- | :-- |
| `glob(patterns, options)` | 查找匹配 glob 模式的文件 |
| `readFile(path)` | 将文件读作字符串( async) |
| `readFileSync(path)` | 将文件读作字符串( 同步) |
| `readFileAsBuffer(path)` | 读取文件为 `Buffer` |
| `write(path, content)` | 将内容写入文件 |
| `writeAsync(path, content)` | 将内容写入文件( 同步) |
| `exists(path)` | 检查路径是否存在 |
| `ensureDir(path)` | 确保目录存在 |
| `copyDir(src, dest)` | 递归复制目录 |
| `copyFile(src, dest)` | 复制单个文件 |
| `remove(path)` | 删除文件或目录 |
| `removeAsync(path)` | 删除文件或目录( 同步) |
| `hash(path)` | 获取文件内容的散列 |
| `gzipFile(path)` | Gzip 一个文件 |
| `gzipDir(path, extensions)` | 目录中的 Gzip 文件 |
| `isDirectory(path)` | 检查路径是否为目录 |
| `realpath(path)` | 将符号链接到条形路径 |
| `stat(path)` | 体型、大小和时间,跟随符号链接 |
| `lstat(path)` | 路径本身的善良、大小和时间 |
| `readdir(path, options)` | 附有此类条目的清单 |
| `readlink(path)` | 读取已存储的符号链接目标 |
| `mkdtemp(prefix)` | 创建一个唯一命名的目录 |
| `tempDir()` | 临时文件的 OS 目录 |
| `rename(src, dest)` | 移动文件或目录 |
| `verifyFileExists(path)` | 如果文件不存在则丢出 |
| `watch(paths, options)` | 监视路径; 返回的控点可以添加更多 |
| `installFileSystem(next)` | 替换全流程 `fileSystem` (测试) |
| `createRecordingFileSystem(inner)` | 环绕 `inner` 并记录每个路径参数 |

`stat`, (中文(简体) ), `lstat` 财务报告和审定财务报表 `readdir` 返回普通对象( e)`isFile`, (中文(简体) ), `isDirectory`, (中文(简体) ), `isSymbolicLink`附加时 `size` 财务报告和审定财务报表 `mtimeMs` 为统计. `readdir(path, { recursive: true })` 还列出子目录,按其路径命名每个条目相对于 `path`。 。 。 . `stat`, (中文(简体) ), `lstat`, (中文(简体) ), `readdir`, (中文(简体) ), `readlink`, (中文(简体) ), `mkdtemp` 财务报告和审定财务报表 `rename` 将节点错误丢出, 不变, 因此可以通过 `error.code === 'ENOENT'`。 。 。 .

## 常见问题

### @ecopages/file-system 是什么？

Ecopage 的节点文件系统工具

### 如何安装 @ecopages/file-system？

在项目目录运行 npm install @ecopages/file-system，或使用 pnpm add / yarn add / bun add。

### @ecopages/file-system 支持 TypeScript 吗？

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

### @ecopages/file-system 支持 ESM 还是 CommonJS？

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

### @ecopages/file-system 需要什么版本的 Node\.js？

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

### @ecopages/file-system 可以商用吗？

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

### @ecopages/file-system 的下载量有多少？

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

### @ecopages/file-system 还在维护吗？

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