# @dirwell/core 中文文档

规范地址：https://npmcn.com/package/%40dirwell/core/

版本：0\.0\.10
npm 元数据更新时间：2026-10-16T11:40:20.885Z
中文译文更新时间：2026-11-13T03:24:50.573Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dirwell/core
原文对照：https://npmcn.com/package/%40dirwell/core/?lang=original
项目主页：https://vp-tw.github.io/dirwell/api-reference/
源码仓库：https://github.com/vp-tw/dirwell

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

- 包体积（解压后）：239 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：2 个
- 首次发布：2026-10-13T05:41:34.843Z
- 最新版本发布：2026-10-16T11:40:20.506Z
- 近 30 天下载量：2383（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

框架中立目录列表和静态发布内核.

## 安装

```sh
npm install @dirwell/core
```

也可以使用：`pnpm add @dirwell/core`、`yarn add @dirwell/core`、`bun add @dirwell/core`

## README

# @ dirwell/ 核心

框架中立文件系统,上市和静态发布SDK. 需要22.12节节点或更新。 为了这个快速开始,安装 `npm install @dirwell/core@0.0.3 @dirwell/theme-plain@0.0.3`。 。 。 .

Core拥有文件系统选择,安全导航,公开上市投影和静态发布. 它需要一个明确的主题,并且不装入默认的主题,图像渲染器,前端框架,配置加载器或监视器. 运行时匹配使用 picomatch 来进行 globs 并忽略 Git 风格忽略文件 .

```js
import { generateExplorer } from "@dirwell/core";
import { createPlainTheme } from "@dirwell/theme-plain";
await generateExplorer({
  sourceDir: "./files",
  outputDir: "./generated",
  theme: createPlainTheme(),
});
console.log("Generated ./generated");
```

创建 `files/note.txt`代码保存为 `build.mjs` 运行 `node build.mjs`。通过 HTTP 完成完整的输出.

稳定控制 : `ignoreFiles` 默认为 `[]`;除非标记可选,否则必须存在明确的文件。 相对路径从 cwd 解析,模式从每个文件目录解析,除非 `baseDir` 已经设定. `outputPolicy: "owned"` 保护非空无标记目的地; 明确 `"replace"` 许可证替换. `dryRun: true` 返回选定的路径和页面计划,而不写入输出。 见 [API 指南](https://vp-tw.github.io/dirwell/api-reference/)。 。 。 .

`generateExplorer` 发布专用输出树. `listing` 独立规划 HTML 页面和数据块; 同步调用可以选择每个目录的计划. 元数据渲染是一个被注入的节点侧提供商. `createDirectoryService` 执行活的,单行本读取而不写出生成的树. 有了过滤器,选择仍然行走物理名称以保留子孙的包容;这不是一个不断成本的索引数据库查询.

该服务拒绝点段,绝对路径,回击,保留根路径和物理根外的路径. Symlink元数据保留了已声明的目标行为. 节点边条目是私人输入; 使用 `projectListingEntry` 在公开系列化之前。 读取不是交易文件系统快照,不具有对抗性同时替换目录的资格.

稳定还增加了经验证的公众 `entryData` 说明和静态 `fileHref` 对已存在的 CDN 文件进行映射 。 见 [API 指南](https://vp-tw.github.io/dirwell/api-reference/#public-annotations-and-file-url-mapping-upcoming-stable) 用于调用时间和公共数据边界.

## 稳定运行时间验证

JavaScript呼叫器接收与打入的消费者相同的识别选项检查:未知的密钥,无效的布林克/enum和畸形排序,同名链接或上市计划在发布出稿前失败. 错误指定完整选项路径并推荐最接近已知的密钥 。 譬如说, `exlcude` 驳回,但建议 `exclude`· ; `mirror: "false"` 被否定,而不是作为真理对待。 上市政策回调在目录检查后进行,其退回的计划在产出替换前经过验证.

自定义主题对象可能携带额外的私有字段 。 他们所要求的名称/交接和已知的钩子必须与主题合同相匹配. 元数据和注释回调仍然是可执行的主机代码,在公共合同同步的情况下等待。 这些控制包括在 `0.0.1`。 。 。 .

0.0.x API可能会进化. 把你的合格版本绑起来 一起升级正式家庭 见 [支助和核查](https://vp-tw.github.io/dirwell/support/) 用于主机、浏览器和设备边界.

## 目录 URL

0.0.3版本使用核心 `routing: { directoryUrls: "explicit" }` 默认 每个主题。 选择 `slash` 用于目录索引主机或 `clean` (单位:千美元) 符合条件的无扩展主机。 主题不重写链接 。 现有来源 主页和下载名称保存;输出冲突失败。 CLI 配置 将路由设置在顶层 `--directory-urls` 超过它. 见 [目录 URL 指导](https://vp-tw.github.io/dirwell/urls/) 用于产出 放置、主机要求、本地 Plain 文件导航和迁移.

## 可选字节格式化

主题收到原始字节数 。 仅在有用时使用浏览器安全程序 :

```ts
import { formatBytes, sizeValue } from "@dirwell/core/format";

formatBytes(1536); // "1.5 KiB"
formatBytes(1536, { units: "decimal" }); // "1.54 kB"
formatBytes(1536, { units: "bytes" }); // "1,536 B"
```

`formatBytes` 接受 `units`, (中文(简体) ), `locale` (默认) `en-US`)和可选 `maximumFractionDigits` 从0到6。 转换的数值否则使用最多3个 数字 字节仍为正整数. 无效或不安全的字节数 扔出; 格式化前处理缺失值.

`sizeValue(entry)` 选择正则文件的字节或允许的同位链接目标 文件字节。 它回来了 `null` 用于不可用的目标和目录. `sizeValue(entry, "entry")` 选择条目的自有字节,包括链接的自有字节 尺寸。 它从不计算目录内容. 独立主题可能忽略两者 帮助和格式化原字段本身.

大小排序是明确的 : `sort.field: "size"` 比较条目大小; `"targetSize"` 比较链接的目标文件大小。 缺失/不可比较值 排序后任意方向的数值,以文件夹为准.

## 常见问题

### @dirwell/core 是什么？

框架中立目录列表和静态发布内核\.

### 如何安装 @dirwell/core？

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

### @dirwell/core 支持 TypeScript 吗？

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

### @dirwell/core 支持 ESM 还是 CommonJS？

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

### @dirwell/core 需要什么版本的 Node\.js？

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

### @dirwell/core 可以商用吗？

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

### @dirwell/core 的下载量有多少？

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

### @dirwell/core 还在维护吗？

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