# @efebia/fastify-auto-import 中文文档

规范地址：https://npmcn.com/package/%40efebia/fastify-auto-import/

版本：1\.2\.1
npm 元数据更新时间：2026-11-12T13:24:14.325Z
中文译文更新时间：2026-11-13T23:07:11.990Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40efebia/fastify-auto-import
原文对照：https://npmcn.com/package/%40efebia/fastify-auto-import/?lang=original
项目主页：https://github.com/efebia-com/be-libs#readme
源码仓库：https://github.com/efebia-com/be-libs

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

- 包体积（解压后）：27.8 kB，18 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2023-01-12T17:11:00.849Z
- 最新版本发布：2026-11-12T13:24:13.881Z
- 近 30 天下载量：2991（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 5 个）

## 中文简介

从目录中自动发现和注册路由插件的快捷插件 .

## 安装

```sh
npm install @efebia/fastify-auto-import
```

也可以使用：`pnpm add @efebia/fastify-auto-import`、`yarn add @efebia/fastify-auto-import`、`bun add @efebia/fastify-auto-import`

## README

# @efebia/ fastify-auto-import

从目录中自动发现和注册路由插件的快捷插件 .

## 安装

```bash
npm install @efebia/fastify-auto-import
```

## 使用量

```ts
import Fastify from 'fastify';
import autoImport from '@efebia/fastify-auto-import';

const fastify = Fastify();

await fastify.register(autoImport, {
  // Required: the starting directory (use import.meta.url in ESM)
  startingDirectory: import.meta.url,
  // Directory to scan, relative to startingDirectory (default: 'src/plugins')
  directory: 'src/plugins',
  // File name to import from each subdirectory (default: 'routes')
  routeFile: 'routes',
  // Subdirectories to skip (default: [])
  excludedDirectories: ['_shared'],
});
```

鉴于以下结构:

```
src/plugins/
  users/
    routes.ts
  orders/
    routes.ts
  _shared/
    utils.ts   ← skipped
```

插件会注册 `users/routes.ts` 财务报告和审定财务报表 `orders/routes.ts` 作为快捷插件.

每个路由文件必须导出默认的快取插件 :

```ts
// src/plugins/users/routes.ts
import type { FastifyPluginAsync } from 'fastify';

const plugin: FastifyPluginAsync = async (fastify) => {
  fastify.get('/users', async () => ({ users: [] }));
};

export default plugin;
```

## API 密码

### `autoImport` (默认导出)

A 类 `fastify-plugin` 兼容插件。 登记在 `fastify.register()`。 。 。 .

**选项** (单位:千美元)`Globber`:

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `startingDirectory` | `string` | —— 说 | **要求.** 基础目录. 过 `import.meta.url` (ESM)或 (中文(简体) ) `__dirname` (中文(简体) ). |
| `directory` | `string` | `'src/plugins'` | 扫描路由子目录, 相对于 `startingDirectory`。 。 。 . |
| `routeFile` | `string` | `'routes'` | 从每个子目录导入文件名( 没有扩展名 ) . |
| `excludedDirectories` | `string[]` | `[]` | 子目录名可跳出. |
| `recursive` | `boolean` | `false` | 扫描给路由文件的嵌入子目录,而不仅仅是直接的孩子. |
| `fileBasedRouting` | `boolean` | `false` | 从路径衍生每个文件夹的 URL 前缀 。 见下文. |
| `log` | `pino.BaseLogger` | 快捷登录 | 导入错误的 Logger 实例 . |

## 递归模式

默认情况下, 插件只看 **直接子目录** 联 合 国 `directory`设置 `recursive: true` 将整个树行走,并在任意深度登记包含路径文件的每个子目录.

```ts
await fastify.register(autoImport, {
  startingDirectory: import.meta.url,
  directory: 'src/plugins',
  recursive: true,
});
```

鉴于这一结构:

```
src/plugins/
  users/
    routes.ts          ← registered
    profile/
      routes.ts        ← registered (nested)
  orders/
    routes.ts          ← registered
    items/
      routes.ts        ← registered (nested)
  _shared/
    utils.ts           ← skipped (no routes file)
```

无 `recursive`,仅限 `users/routes.ts` 财务报告和审定财务报表 `orders/routes.ts` 将注册。 与 `recursive: true`, (中文(简体) ), `users/profile/routes.ts` 财务报告和审定财务报表 `orders/items/routes.ts` 也会被捡起.

`excludedDirectories` 仍然适用于每个深度——一个匹配的目录名称连同其所有后人一起被跳过.

## 基于文件的路由

设定 `fileBasedRouting: true` 以创建文件夹 URL。 它走着整棵树(不需要 `recursive`) (中文(简体) ).

```
src/routes/
  api/
    users/
      routes.ts            ← /api/users
      get.ts               ← plain handler, imported by routes.ts (not auto-loaded)
      [userId]/
        routes.ts          ← /api/users/:userId
    (private)/
      tasks/routes.ts      ← /api/tasks  ((private) adds no segment)
```

-   完整文件夹路径为 URL. 每个 `routes.ts` 在自己的封装范围内,该路径为: `prefix`,因此它只声明与其文件夹相对的路径(`app.get('/', ...)`, (中文(简体) ), `app.get('/export', ...)`) (中文(简体) ).
-   范围是独立的: 母文件夹中的钩 `routes.ts` 绝不适用于儿童文件夹(反之亦然).
-   `[id]` 变成 `:id`指定文件夹 `_x` 或者说 `(group)` 添加无段.
-   只有 `routes` 文件已装入。 文件夹中的任何其它内容( 处理器, 计程器) 都由您导入 .
-   中间软件不是内置的。 添加钩子或 `preHandler`单位中 `routes.ts` 这需要他们.
-   `excludedDirectories` 财务报告和审定财务报表 `routeFile` 像往常一样.

## 许可证

麻省理工学院

## 常见问题

### @efebia/fastify-auto-import 是什么？

从目录中自动发现和注册路由插件的快捷插件 \.

### 如何安装 @efebia/fastify-auto-import？

在项目目录运行 npm install @efebia/fastify-auto-import，或使用 pnpm add / yarn add / bun add。

### @efebia/fastify-auto-import 支持 TypeScript 吗？

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

### @efebia/fastify-auto-import 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @efebia/fastify-auto-import 可以商用吗？

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

### @efebia/fastify-auto-import 的下载量有多少？

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

### @efebia/fastify-auto-import 还在维护吗？

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