# @feature-sliced/filesystem 中文文档

规范地址：https://npmcn.com/package/%40feature-sliced/filesystem/

版本：3\.1\.1
npm 元数据更新时间：2026-08-25T22:28:19.476Z
中文译文更新时间：2026-11-14T12:55:39.526Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40feature-sliced/filesystem
原文对照：https://npmcn.com/package/%40feature-sliced/filesystem/?lang=original
项目主页：https://github.com/feature-sliced/filesystem

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

- 包体积（解压后）：62.9 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-01-24T18:02:50.673Z
- 最新版本发布：2026-08-25T22:28:19.317Z
- 近 30 天下载量：731075（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 2 个）

## 中文简介

一套用于查找文件系统中的FSD根并与之合作的公用设备.

## 安装

```sh
npm install @feature-sliced/filesystem
```

也可以使用：`pnpm add @feature-sliced/filesystem`、`yarn add @feature-sliced/filesystem`、`bun add @feature-sliced/filesystem`

## README

# @ feature- sliced/ 文件系统

![npm version](https://img.shields.io/npm/v/@feature-sliced/filesystem) ![minzipped package size](https://img.shields.io/bundlephobia/minzip/@feature-sliced/filesystem.svg)

一套用于查找文件系统中的FSD根并与之合作的公用设备.

该项目旨在开发工具,用于 [特色设计](https://feature-sliced.design/)。 。 。 .

## 安装

```bash
pnpm add @feature-sliced/filesystem
```

```bash
npm install --save @feature-sliced/filesystem
```

类型定义构建于QQ.

## API 密码

### `resolveImport`

```ts
function resolveImport(
  importedPath: string,
  importerPath: string,
  tsCompilerOptions: typescript.CompilerOptions,
  fileExists: (path: string) => boolean,
  directoryExists?: (path: string) => boolean,
): string | null;
```

给出文件名、 导入路径和 TSConfig 对象, 生成导入文件的路径, 相对于 TypeScript 的路径 `baseUrl`。 。 。 .

示例

```tsx
// /project/src/pages/home/ui/HomePage.tsx
import { Button } from "~/shared/ui";
```

```json
// ./tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "Bundler",
    "baseUrl": ".",
    "paths": {
      "~/*": ["./src/*"]
    }
  }
}
```

```tsx
resolveImport(
  "~/shared/ui",
  "./src/pages/home/ui/HomePage.tsx",
  { moduleResolution: "Bundler", baseUrl: ".", paths: { "~/*": ["./src/*"] } },
  fs.existsSync,
);
```

预期产出: `/project/src/shared/ui/index.ts`。 。 。 .

### `layerSequence`, (中文(简体) ), `unslicedLayers`,以及 `conventionalSegmentNames`

FSD中重要名称的定义.

```ts
export const layerSequence: Array<LayerName> = [
  "shared",
  "entities",
  "features",
  "widgets",
  "pages",
  "app",
];
export const unslicedLayers = ["shared", "app"];
export const conventionalSegmentNames = ["ui", "api", "lib", "model", "config"];
```

### FSD - 意识向上

简单表示文件系统的一组倒转函数 :

```ts
export interface File {
  type: "file";
  path: string;
}

export interface Folder {
  type: "folder";
  path: string;
  children: Array<File | Folder>;
}
```

所有倒转函数在层文件夹上识别前缀(下划线或数字后加下划线等). `_app` 或者说 `6_shared`) (中文(简体) ). 图层名称总是在没有前缀的情况下报告,而返回的则 `Folder` 对象保留物理、前缀路径.

#### `getLayers`

```ts
export type LayerName =
  | "shared"
  | "entities"
  | "features"
  | "widgets"
  | "pages"
  | "app";

function getLayers(fsdRoot: Folder): Partial<Record<LayerName, Folder>>;
```

从 FSD 根中提取层 。 返回图层名称映射到文件夹对象。 前缀地层( 如. `6_shared`, (中文(简体) ), `_app`) 被绘制到其冠名上(`shared`, (中文(简体) ), `app`) (中文(简体) ). 当同一层的前缀和非前缀的变体同时存在时,前缀的一取胜.

#### `getSlices`

```ts
function getSlices(
  slicedLayer: Folder,
  additionalSegmentNames: Array<string> = [],
): Record<string, Folder>;
```

从 a 提取切片 **切开** 层。 返回切片名称映射( 可能包含斜线) 到文件夹对象 .

当文件夹至少有一个文件夹/文件并有常规片段的名称时, 就会被检测为切片(`ui`, (中文(简体) ), `api`, (中文(简体) ), `model`, (中文(简体) ), `lib`, (中文(简体) ), `config`) (中文(简体) ). 如果您的工程包含没有这些片段的片段,您可以提供额外的片段名称.

#### `getSegments`

```ts
function getSegments(
  sliceOrUnslicedLayer: Folder,
): Record<string, Folder | File>;
```

从切片或切片取出片段 **未切开** 层。 将分区名称映射到文件夹或文件对象.

#### `getAllSlices`

```ts
function getAllSlices(
  fsdRoot: Folder,
  additionalSegmentNames: Array<string> = [],
): Record<string, Folder & { layerName: string }>;
```

从 FSD 根的所有层提取切片 。 返回切片名称映射到文件夹对象( 可能包含斜线), 并加增 `layerName` 属性。 这个 `layerName` 是条形(前缀-已勾接)层名.

当文件夹至少有一个文件夹/文件并有常规片段的名称时, 就会被检测为切片(`ui`, (中文(简体) ), `api`, (中文(简体) ), `model`, (中文(简体) ), `lib`, (中文(简体) ), `config`) (中文(简体) ). 如果您的工程包含没有这些片段的片段,您可以提供额外的片段名称.

#### `getAllSegments`

```ts
function getAllSegments(fsdRoot: Folder): Array<{
  segment: Folder | File;
  segmentName: string;
  sliceName: string | null;
  layerName: LayerName;
}>;
```

从 FSD 根的所有切片和分层中提取段 。 在 FSD 根( 层, 切片) 中返回一个平整的段数组及其名称和位置 .

#### `isSliced`

> \[注\]  
> 不要和他们混淆 `isSlice`,这个函数根据文件夹包含的片段来决定文件夹是否像切片.

```ts
export type LayerName =
  | "shared"
  | "entities"
  | "features"
  | "widgets"
  | "pages"
  | "app";

function isSliced(layerOrName: Folder | LayerName): boolean;
```

确定此层是否被切开 。 您可以通过一层的文件夹或名称( 小写) 。 只有共享层和App层没有被切片,其余部分是.

#### `getIndexes`

```ts
function getIndexes(fileOrFolder: File | Folder): File[];
```

获取切片或片段的索引(公共 API) 。 当一个片段是一个文件时,它是它自己的索引. 当一个片段是文件夹时,它会返回该文件夹内的一系列索引文件. 多个索引文件(例如, `index.client.js`, (中文(简体) ), `index.server.js`) 得到支持.

#### `isIndex`

```ts
function isIndex(fileOrFolder: File | Folder): boolean;
```

确定一个给定的文件或文件夹是否是一个索引文件(只有文件可以成为索引,为方便而接受文件夹,但总是返回虚假).

#### `isSlice`

> \[注\]  
> 不要和他们混淆 `isSliced`,该函数根据 FSD 确定一个层是否包含切片.

```ts
function isSlice(
  folder: Folder,
  additionalSegmentNames: Array<string> = [],
): boolean;
```

确定此文件夹是否为切片 .

剪切被定义为包含至少一个部分的文件夹. 如果项目中的某些片段仅包含非常规片段,则可以提供额外的片段名称.

#### `isCrossImportPublicApi`

```ts
function isCrossImportPublicApi(
  file: File,
  {
    inSlice,
    forSlice,
    layerPath,
  }: { inSlice: string; forSlice: string; layerPath: string },
): boolean;
```

检查某个文件是否是切片中定义的交叉导入公共 API `inSlice` 切片时 `forSlice` 在某一层.

例如:

```ts
const file = { path: "./src/entities/user/@x/product.ts", type: "file" };
isCrossImportPublicApi(file, {
  inSlice: "user",
  forSlice: "product",
  layerPath: "./src/entities",
}); // true
```

## 常见问题

### @feature-sliced/filesystem 是什么？

一套用于查找文件系统中的FSD根并与之合作的公用设备\.

### 如何安装 @feature-sliced/filesystem？

在项目目录运行 npm install @feature-sliced/filesystem，或使用 pnpm add / yarn add / bun add。

### @feature-sliced/filesystem 支持 TypeScript 吗？

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

### @feature-sliced/filesystem 支持 ESM 还是 CommonJS？

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

### @feature-sliced/filesystem 可以商用吗？

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

### @feature-sliced/filesystem 的下载量有多少？

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

### @feature-sliced/filesystem 还在维护吗？

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