---
title: "fs.stat"
description: "查询虚拟文件或目录的类型、大小和修改时间。"
---


> 查询虚拟文件或目录的类型、大小和修改时间，不跟随符号链接。

## 签名

```ts
KSM.fs.stat(args: {
  path: string;
}): Promise<KSMFileMetadata>
```

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

## 平台与权限

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

## 参数

|参数 |类型 |必填 |说明 |
| --- | --- | --- | --- |
| `path` | `string` |是 |文件、目录或有效 picked 句柄的虚拟路径 |

可查询 `app://data`、`app://cache`、`app://tmp`、`app://res`、`app://assets`
以及 `app://picked/<id>`。虚拟根路径本身可以查询，`app://picked` 根不可查询。

## 返回值

|字段 |类型 |说明 |
| --- | --- | --- |
| `kind` | `'file' \| 'directory'` |资源类型 |
| `size` | `number` |文件字节数；目录固定为 `0` |
| `modifiedAt` | `number \| null` |Unix 毫秒；宿主无法提供时为 `null` |

返回的是元数据快照，不保证文件内容在后续读取时仍保持不变。

## 行为

- 可写沙箱、只读资源和有效 picked 句柄都支持。
- `app://res` 和 `app://assets` 的修改时间可能为 `null`。
- 符号链接不会被跟随，查询符号链接会按不可用资源处理。
- 目标不存在、picked token 未登记或资源无法读取时返回 `NOT_FOUND`。
- 目录 `size` 不使用目录项数量或磁盘占用代替。

## 示例

```ts
const metadata = await KSM.fs.stat({
  path: 'app://data/config.json'
});

if (metadata.kind === 'file') {
  console.info(metadata.size, metadata.modifiedAt);
}
```

## 错误

|错误 |场景 |
| --- | --- |
|普通 `TypeError` |路径未通过前端元数据守卫 |
| `INVALID_ARGS` |宿主参数校验失败 |
| `PERMISSION_DENIED` |路径越出可读沙箱，或权限不可用 |
| `NOT_FOUND` |目标不存在、picked token 无效或符号链接不可用 |
| `NOT_SUPPORTED` |对应文件或资源服务未配置 |
| `TIMEOUT` |宿主未在默认时间内响应 |

## 相关

- [fs.readDir](/docs/kasumi/api/fs/read-dir)
- [fs.mkdir](/docs/kasumi/api/fs/mkdir)
- [types](/docs/kasumi/api/types)