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

新檔案的名稱。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需預先加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

[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