writefile

定义

writefile通常指编程环境中负责把一段内存数据落到文件或设备上的接口。在 Windows 平台上，其正式名称写作 WriteFile，声明于 fileapi.h 头文件，原型为 BOOL WriteFile(HANDLE hFile, LPCVOID lpBuffer, DWORD nNumberOfBytesToWrite, LPDWORD lpNumberOfBytesWritten, LPOVERLAPPED lpOverlapped)。该函数并不只面向磁盘文件，hFile 也可以是文件流、物理磁盘、卷、控制台缓冲区、磁带机、套接字、通信资源、邮槽或管道等的句柄。

由于同名或近名接口广泛存在于不同语言与框架中，writefile 也常被当作一类“写文件操作”的通称。例如 Node.js 的 fs 模块提供 fs.writeFile，用于异步写入文件并在文件已存在时替换其内容^[1]，语言层面的拼写差异（WriteFile 与 writeFile）在讨论中常被混用。

原理

Windows 版 WriteFile 的核心参数分工明确：hFile 为已取得写权限的句柄，lpBuffer 指向待写入数据的缓冲区，nNumberOfBytesToWrite 给出字节数，lpNumberOfBytesWritten 用于回填实际写入的字节数，lpOverlapped 在重叠（异步）操作时指向 OVERLAPPED 结构。函数成功时返回非零值，失败或异步未完成时返回零，详细错误码需调用 GetLastError 获取。

写入长度为零时属于空写操作，不会写入字节，也不会截断或扩展文件；若需改变文件长度，应调用 SetEndOfFile^[2]。此外，若目标文件的一部分被其他进程锁定，且写操作覆盖了被锁区间，该调用会失败^[3]。调用方在写操作完成前不得读取、重新分配或释放该输出缓冲区，否则可能破坏写入的数据^[3]。

在同步与异步两种模式上，WriteFile 既可用于同步也可用于异步，而同类函数 WriteFileEx 只能执行异步写入，并在写入完成或取消、且调用线程处于可警告等待状态时调用指定的完成例程。重叠操作要求句柄以 FILE_FLAG_OVERLAPPED 打开，若操作未立即完成，函数返回 FALSE 且 GetLastError 给出 ERROR_IO_PENDING，后者并不表示失败^[4]。

发展历程

WriteFile 属于 Windows 的经典文件 API 体系，与 CreateFile、ReadFile、CloseHandle 等函数配合构成文件读写的完整流程。在 Windows CE 与 Windows Mobile 等嵌入式平台上，微软提供了对应的 RAPI 版本，名为 CeWriteFile^[3]。相关平台文档在 2010 年前后仍在更新，说明该接口长期保持兼容^[3]。

随着跨平台运行环境普及，同名接口出现在更多技术栈中。Node.js 的文件系统模块长期提供 fs.writeFile，并在后续版本中加入以 AbortSignal 取消写入的选项，取消被称为“尽力而为”，仍可能写入部分数据^[1]。前端测试框架 Cypress 则提供 cy.writeFile 命令，把文本、数组或对象写入项目目录内的文件。这些接口并非对 Windows 函数的移植，而是各自平台对“写文件”这一操作的抽象。

应用

在 Windows 原生开发中，WriteFile 的用途超出普通文本文件。它可向控制台输出缓冲区写入字符，写入位置从当前光标处开始，写完后光标位置随之更新，具体行为由控制台模式决定^[2]。写串行通信设备时，函数行为受 SetCommTimeouts 与 GetCommTimeouts 设定的超时参数影响^[2]。

在脚本与自动化场景中，写文件接口用于生成配置、日志与测试夹具。Cypress 的 cy.writeFile 可把接口响应内容保存为夹具文件，供后续测试读取。在 Go 生态中，有第三方包以 writefile 命名，采用先写临时文件、fsync 后再 rename 的方式原子替换目标文件，以避免程序崩溃时留下残缺文件^[5]。

科学计算与移动脚本工具也引入类似命令。粒子物理与天体物理常用的 Genesis 工具提供 writefile 例程，在 openfile 打开文件后按参数追加带换行的文本行，并可用 -format 指定格式化字符串，改动在 closefile 或 flushfile 后才永久生效^[6]。触控脚本开发库 TSLib 的 writeFile 则把表格内容写入文件，支持清空写入与追加写入两种模式^[7]。

局限

WriteFile 只负责按字节搬运数据，不做编码转换。向控制台以宽字符写入时，若处理不当可能出现字符间插入空隙的现象，需要配合控制台专用的宽字符接口^[8]。它也不提供截断能力，零字节写入不会改变文件长度，长度调整需另用 SetEndOfFile^[2]。

异步写入的完成通知与线程状态相关。WriteFileEx 的完成例程必须在调用线程进入可警告等待状态时才被调用，若线程未处于该状态，系统会排队等待。取消挂起的异步 I/O 需要 CancelIo 或 CancelIoEx，被取消的操作以 ERROR_OPERATION_ABORTED 结束。

高层封装同样存在边界。Node.js 文档指出，在同一文件上不等待回调就多次调用 fs.writeFile 是不安全的，此类场景应改用 createWriteStream；fs.writeFile 内部会执行多次 write 调用，性能敏感的代码应改用流式写入^[1]。若以文件描述符而非文件名调用，文件不会被替换，原有数据可能残留在新写入内容之前或之后^[9]。此外，Cypress 的 cy.writeFile 只能写入项目根目录范围内的路径。

参见

• ReadFile —— 与 WriteFile 对应的读取接口，二者共同构成 Windows 文件读写的基本操作。

• CreateFile —— 用于获取文件或设备句柄，是调用 WriteFile 前必需的准备步骤。

• OVERLAPPED 结构 —— 承载异步写入的偏移与状态信息，决定重叠 I/O 的执行方式。

• 文件描述符 —— 操作系统标识打开文件的整型句柄，多种 writefile 接口可接受该参数。

• Node.js —— 其 fs 模块提供 fs.writeFile，是服务器端常见的写文件接口。

• 原子写入 —— 通过临时文件加改名保证文件完整性的写入策略。