---
title: "fs.mkdir"
description: "在可写虚拟沙箱中创建目录并返回是否实际新建。"
---


> 在可写虚拟沙箱中创建目录，并区分新建成功与已存在目录。

## 签名

```ts
KSM.fs.mkdir(args: {
  path: string;
  recursive?: boolean;
}): Promise<{ created: boolean }>
```

命名导出调用形式相同：`fs.mkdir({ path, recursive })`。

## 平台与权限

| Windows | Android |权限 |
| --- | --- | --- |
|支持 |支持 | `fs.write` |

## 参数

|参数 |类型 |必填 |说明 |
| --- | --- | --- | --- |
| `path` | `string` |是 |目标目录的 `app://` 虚拟路径 |
| `recursive` | `boolean` |否 |是否递归创建父目录，缺省为 `false` |

`path` 只能位于 `app://data`、`app://cache` 或 `app://tmp`。`app://res`、
`app://assets` 和 `app://picked` 都不可创建目录。

## 返回值

|字段 |类型 |说明 |
| --- | --- | --- |
| `created` | `boolean` |本次是否实际创建了目录 |

目标目录已经存在且是普通目录时返回 `{ created: false }`。这是一个幂等结果，
调用方不需要把它当成错误。

## 行为

- `recursive: false` 时，父目录不存在会失败。
- `recursive: true` 时，会创建缺失的父目录。
- 目标已存在但为文件或符号链接时返回 `IO_ERROR`。
- 目录根 `app://data`、`app://cache`、`app://tmp` 已存在时返回
  `{ created: false }`。
- 目录路径可以带末尾 `/`，但不能包含重复尾斜杠、反斜杠、`..`、`~` 或空字节。

## 示例

```ts
const result = await KSM.fs.mkdir({
  path: 'app://data/exports/2026',
  recursive: true
});

if (result.created) {
  console.info('目录已创建');
}
```

## 错误

|错误 |场景 |
| --- | --- |
|普通 `TypeError` |路径未通过前端目录守卫，或 `recursive` 不是布尔值 |
| `INVALID_ARGS` |宿主参数校验失败 |
| `PERMISSION_DENIED` |路径位于只读根、picked 句柄或沙箱外 |
| `IO_ERROR` |目标已存在但不是普通目录，或创建失败 |
| `NOT_SUPPORTED` |文件系统服务未配置 |
| `TIMEOUT` |宿主未在默认时间内响应 |

## 相关

- [fs.readDir](/docs/kasumi/api/fs/read-dir)
- [fs.stat](/docs/kasumi/api/fs/stat)
- [fs 模块](/docs/kasumi/api/fs)