URL: /built-in/file_write

---
title: file_write — 写入文件
description: 创建新文件或完整覆盖已有文件的内容，含预读检查和二进制检测
---

创建新文件或完整覆盖已有文件的内容。对于已有文件的小范围修改，建议使用 `file_edit` 工具。

**适用场景**：让 AI 创建新文件、生成代码文件、写入配置文件、覆盖更新已有文件等。

## 参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `file_path` | string | 是 | 要写入的文件的绝对路径 |
| `content` | string | 是 | 要写入的完整文件内容 |

## 约束与限制

| 限制项 | 值 |
|--------|:----:|
| 写入内容 | 仅支持纯文本文件（UTF-8 编码） |
| 不支持的类型 | 二进制文件（含 null byte 序列）|
| 父目录 | 自动创建不存在的父目录 |

## 安全机制

| 防护项 | 说明 |
|--------|------|
| 预读检查 | 覆盖已有文件前，必须先通过 `file_read` 读取过该文件 |
| 目录检测 | 检测到路径是目录时拒绝写入 |
| 二进制检测 | 扫描内容前 8KB，含 null byte 则判定为二进制内容 |
| 自动建目录 | 父目录不存在时自动创建 |

## 与 file_edit 的区别

> **file_edit** 用于对已有文件进行精确字符串替换（小范围修改）。  
> **file_write** 用于创建新文件或完整覆盖已有文件（全量写入）。  
> AI Agent 会根据场景自动选择：新建文件用 `file_write`，修改现有内容用 `file_edit`。

## 错误场景

| 错误类型 | 说明 |
|----------|------|
| 缺少 `file_path` | 未提供必填参数 |
| 缺少 `content` | 未提供必填参数 |
| 路径是目录 | 写入路径指向目录 |
| 二进制内容 | 内容包含 null byte |
| 创建目录失败 | 父目录创建权限不足等 |

## 使用示例

```bash
zapmyco run '在 src/ 下创建一个新的模块文件 utils/helpers.rs'
zapmyco run '生成一个 Cargo.toml 配置文件'
zapmyco run '将重构后的代码写入到 src/new_implementation.rs'
```

## 相关文档

- [内置工具目录](/guide/built-in-tools) — 查看所有工具
- [file_edit](/built-in/file_edit) — 对已有文件进行精确修改
- [file_read](/built-in/file_read) — 读取文件内容