CopyFileW 函数（winbase.h）

项目
11/20/2024

将现有文件复制到新文件。

CopyFileEx 函数提供了两个附加功能。 CopyFileEx 每次完成复制操作时都可以调用指定的回调函数，CopyFileEx 可以在复制操作期间取消。

若要将此操作作为事务处理操作执行，请使用 CopyFileTransacted 函数。

语法

BOOL CopyFileW(
  [in] LPCWSTR lpExistingFileName,
  [in] LPCWSTR lpNewFileName,
  [in] BOOL    bFailIfExists
);

参数

[in] lpExistingFileName

现有文件的名称。

默认情况下，名称限制为MAX_PATH个字符。若要将此限制扩展到 32,767 宽字符，请将“\\？\”前面追加到路径。有关详细信息，请参阅命名文件、路径和命名空间。

提示

从 Windows 10 版本 1607 开始，你可以选择加入以删除MAX_PATH限制，而无需追加“\\？\”。有关详细信息，请参阅命名文件、路径和命名空间的“最大路径长度限制”部分。

如果 lpExistingFileName 不存在，CopyFile 失败，GetLastError 返回 ERROR_FILE_NOT_FOUND。

[in] lpNewFileName

新文件的名称。

提示

[in] bFailIfExists

如果此参数 TRUE，并且 lpNewFileName 指定的新文件已存在，则函数将失败。如果此参数 FALSE 且新文件已存在，则函数将覆盖现有文件并成功。

返回值

如果函数成功，则返回值为非零。

如果函数失败，则返回值为零。若要获取扩展的错误信息，请调用 GetLastError。

言论

现有文件的安全资源属性（ATTRIBUTE_SECURITY_INFORMATION）将复制到新文件。

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP ：在 Windows 8 和 Windows Server 2012 之前，不会将现有文件的安全资源属性复制到新文件中。

现有文件的文件属性将复制到新文件。例如，如果现有文件具有 FILE_ATTRIBUTE_READONLY 文件属性，则通过调用 CopyFile 创建的副本也将具有 FILE_ATTRIBUTE_READONLY 文件属性。有关详细信息，请参阅检索和更改文件属性。

如果目标文件已存在并且设置了 FILE_ATTRIBUTE_HIDDEN 或 FILE_ATTRIBUTE_READONLY 属性，则此函数将失败并 ERROR_ACCESS_DENIED。

CopyFile 用于复制加密文件时，它会尝试使用源文件加密中使用的密钥加密目标文件。如果无法执行此操作，此函数将尝试使用默认密钥加密目标文件。如果这两种方法都无法完成，CopyFile 失败，并出现 ERROR_ENCRYPTION_FAILED 错误代码。

符号链接行为 - 如果源文件是符号链接，则复制的实际文件是符号链接的目标。

如果目标文件已存在并且是符号链接，则符号链接的目标将被源文件覆盖。

在 Windows 8 和 Windows Server 2012 中，以下技术支持此函数。

科技	支持
服务器消息块（SMB） 3.0 协议	是的
SMB 3.0 透明故障转移（TFO）	是的
具有横向扩展文件共享的 SMB 3.0 （SO）	是的
群集共享卷文件系统（CsvFS）	是的
可复原文件系统（ReFS）	是的

例子

有关示例，请参阅检索和更改文件属性。

注意

winbase.h 标头将 CopyFile 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。

要求

要求	价值
最低支持的客户端	Windows XP [桌面应用 \|UWP 应用]
支持的最低服务器	Windows Server 2003 [桌面应用 \|UWP 应用]
目标平台	窗户
标头	winbase.h （包括 Windows.h）
库	Kernel32.lib
DLL	Kernel32.dll