# @hattip/walk 中文文档

规范地址：https://npmcn.com/package/%40hattip/walk/

版本：0\.0\.49
npm 元数据更新时间：2024-11-03T17:29:54.852Z
中文译文更新时间：2026-11-17T11:46:27.155Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40hattip/walk
原文对照：https://npmcn.com/package/%40hattip/walk/?lang=original
项目主页：https://github.com/hattipjs/hattip#readme
源码仓库：https://github.com/hattipjs/hattip

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

- 包体积（解压后）：16 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- 首次发布：2023-08-27T08:09:01.783Z
- 最新版本发布：2024-11-02T10:59:08.368Z
- 近 30 天下载量：28543（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 0 个）

## 中文简介

从目录创建文件显示

## 安装

```sh
npm install @hattip/walk
```

也可以使用：`pnpm add @hattip/walk`、`yarn add @hattip/walk`、`bun add @hattip/walk`

## README

# `@hattip/walk`

用于行走目录并生成用于执行静态文件服务器的文件清单的实用软件包 .

使用这个软件包有两种方法:

-   你也可以使用一个 `walk`, (中文(简体) ), `createFileSet`, (中文(简体) ), `createFileMap`,或 `createFileList` 服务器启动期间运行时的函数,并使用结果执行静态文件服务器,
-   或者你可以使用CLI或其中之一 `createFileSetModule`, (中文(简体) ), `createFileListModule`,或 `createCompressedFileListModule` 函数在构建时生成一个显示模块,以改善无服务器环境中的寒冷起动时间.

## 文件名称正常化

`@hattip/walk` 规范文件名称,使其安全用于URL的路径部分.

## 明显类型

这个工具可以生成三种类型的运算表:

-   A 类 **文件集显示** 是一组简单的文件名.
-   A 类 **文件地图显示** 是一个将 URL 规范化的文件名映射到文件路径的地图 .
-   A 类 **文件列表显示** 由 URL 规范化文件名称、路径、大小、散列和可选的 ETags 组成.

### 文件集列表

使用 `--set` 旗帜或 `createFileSetModule` 函数。 这是一个模块,其界面如下:

```ts
const files: Set<string>;
export default files;
```

导出集是类似此的一组文件路径 :

```js
export default new Set([
  "/LICENSE",
  "/cli.js",
  "/package.json",
  "/readme.md",
  "/%D83D%DE42.txt", // 🙂.txt percent-encoded
]);
```

当平台提供静态文件服务器时,这种类型的表单是有用的,但需要快速检查,以查看在调用静态文件处理器之前是否存在文件.

### 文件地图显示

使用 : `--map` 旗帜或 `createFileMapModule` 函数。 这是一个模块,其界面如下:

```ts
const files: Map<string, string | undefined>;
export default files;
```

将地图命名为 `undefined` 是不需要正常化的名字 示例输出如下:

```ts
export default new Map([
  ["/LICENSE"],
  ["/cli.js"],
  ["/package.json"],
  ["/readme.md"],
  ["/%D83D%DE42.txt", "/🙂.txt"],
]);
```

### 文件列表显示

文件列表列表生成时,既不是 `--set` 也没有 `--map` 使用或调用旗帜 `createFileListModule` 函数。 这是一个模块,其界面如下:

```ts
const files: Array<
  [
    name: string,
    path: string | undefined, // undefined for names that don't require normalization
    size: number,
    hash: string,
    etag?: string,
  ]
>;
export default files;
```

ETag 生成可以通过路过被禁用 `--no-etag` 或通过 `false` 中的相关选项 `createFileListModule` 函数.

导出列表是类似此的拖曳阵列 :

```js
export default [
  [
    "/LICENSE",
    ,
    "application/octet-stream",
    1069,
    "10094a766eba8c1f9e9377874ad0832b12a9af93ec9ff08bee0d95e1fef9ae40",
  ],
  [
    "/cli.js",
    ,
    "application/javascript",
    44,
    "0779d059d458628cb4ab06c3e7d2a7e5b5e40698fce230c5aa0908bbb844f40b",
  ],
  [
    "/package.json",
    ,
    "application/json",
    1208,
    "e28324f872c5805cc5f36f261ecdba122b80df060d200edd4d2dc1a54af6217d",
  ],
  [
    "/readme.md",
    ,
    "text/markdown",
    5746,
    "3644ce0612c829bff249628b1f6dd23b4de62c5b3d1230ebceaccd6db8f9f69a",
  ],
  [
    "/%D83D%DE42.txt",
    "/🙂.txt",
    "text/plain",
    14,
    "df7a1ec45c1f8f13aa902a819a1d19d8707e6e8b5398803853d0489bf6d603c0",
  ],
];
```

通过使用 `--compress` CLI旗或称 `createCompressedFileListModule` 函数,可以生成一个略为压缩的表单版本,该表单不重复每个文件的内容类型。 这对于对部署的代码有限度的平台可能有用。 假设 ETag 生成被禁用, 输出看起来是这样的( 第二个元素是其中的内容类型的索引) `types` 数组 :

```ts
export default {
  types: [
    "application/octet-stream",
    "application/javascript",
    "application/json",
    "text/markdown",
    "text/plain",
  ],
  files: [
    ["/LICENSE", , 0, 1069],
    ["/cli.js", , 1, 44],
    ["/package.json", , 2, 1208],
    ["/readme.md", , 3, 5028],
    ["/%D83D%DE42.txt", "/🙂.txt", 4, 14],
  ],
};
```

接口如下:

```ts
const manifest: {
  types: string[];
  files: Array<
    [
      name: string,
      path: string | undefined, // undefined for names that don't require normalization
      type: number,
      size: number,
      hash: string,
      etag?: string,
    ]
  >;
};

export default manifest;
```

## 这个 `prune` 选项

默认, `@hattip/walk` 跳过 `node_modules`, (中文(简体) ), `dist`,以及任何以点开头的文件,但 `.well-known`。您可以用 `prune` 选项,可接受字符串或正则表达式的数组。 正则表达式必须以 `/` 当使用 CLI 时.

## 常见问题

### @hattip/walk 是什么？

从目录创建文件显示

### 如何安装 @hattip/walk？

在项目目录运行 npm install @hattip/walk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hattip-walk，可以用 npx hattip-walk 直接运行。

### @hattip/walk 支持 TypeScript 吗？

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

### @hattip/walk 支持 ESM 还是 CommonJS？

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

### @hattip/walk 可以商用吗？

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

### @hattip/walk 的下载量有多少？

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

### @hattip/walk 还在维护吗？

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

