跳至主要內容

拷貝檔案或目錄 (file.copy)

聲明​

操作成敗, 錯誤資訊 = file.copy(來源路徑, 目標路徑 [, 模式])

參數​

  • 來源路徑
    文字型,來源檔案或目錄的絕對路徑
  • 目標路徑
    文字型,拷貝後的檔案或目錄的完整絕對路徑,包含目標檔名或目錄名
  • 模式 20250914+
    文字型,可選參數,複製模式。取值:
    • 空字串或省略:預設模式(no-clobber),當目標已存在時回傳失敗
    • "overwrite" 或 "o":覆蓋模式,直接替換已存在的目標(已存在的目標會被刪除)
    • "merge" 或 "m":合併模式(僅用於目錄),保留目標中已存在的檔案
    • "overwrite-merge" 或 "om"/"mo":覆蓋合併模式,合併目錄但覆蓋同名檔案

回傳值​

  • 操作成敗
    布林型,操作成功回傳 true,操作失敗回傳 false
  • 錯誤資訊
    文字型,操作失敗時的錯誤資訊

說明​

將 來源路徑 指向的檔案或目錄拷貝為 目標路徑
該函式是「拷貝為」語義,不是「拷貝進」語義。目標路徑 指定最終的檔案或目錄,不會自動追加來源檔名或目錄名;即使目標已存在且為目錄,或者目標路徑以 / 結尾,也不會將來源檔案或目錄放入該目錄中
例如,要把 /a/b/c 拷貝到 /d/e/ 中並保留名稱 c,目標路徑應寫為 /d/e/c,不能只寫 /d/e/
目標已存在時,按 模式 參數處理:預設模式回傳失敗,覆蓋模式替換目標本身,目錄合併模式則將來源目錄內容合併到目標目錄
關鍵詞:複製檔案、拷貝檔案、複製目錄、拷貝目錄、複製資料夾、拷貝資料夾
該函式在 20250313 以後的版本方可使用

範例​

ok, err = file.copy(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
sys.alert('拷貝失敗:'..err)
end

注:上述程式碼中使用了非本章函式 sys.alert

拷貝到另一個目錄並保留名稱​

-- 假設 /d/e 是已存在的目錄,/d/e/c 尚不存在
file.copy('/a/b/c', '/d/e/c') -- 正確:將 c 拷貝為 /d/e/c

-- 錯誤寫法:目標是 e 本身,不是 e 目錄中的 c
file.copy('/a/b/c', '/d/e/') -- 預設模式下因目標已存在而失敗

-- 覆蓋模式會替換 e 本身,不會生成 /d/e/c(20250914+)
-- file.copy('/a/b/c', '/d/e/', 'overwrite')

封裝「拷貝進目錄」函式​

以下為自訂封裝範例,需要 20250914 以後的版本。目標目錄須已存在,函式會保留來源檔案或目錄名,並將可選的 mode 參數傳給 file.copy。發生同名衝突時,仍按指定模式處理。

local function file_copy_into(src_path, dst_dir, mode)
if file.exists(dst_dir) ~= "directory" then
return false, "Target is not a directory"
end

local name, err = file.path.last_component(src_path)
if not name then
return false, err
end
-- 避免將目標目錄本身或其父目錄作為最終目標。
if name == "" or name == "/" or name == "." or name == ".." then
return false, "Source path must end with a file or directory name"
end

local dst_path, path_err = file.path.add_component(dst_dir, name)
if not dst_path then
return false, path_err
end
return file.copy(src_path, dst_path, mode)
end

-- 假設 /d/e 是已存在的目錄,將 c 拷貝為 /d/e/c
local ok, err = file_copy_into("/a/b/c", "/d/e/")
if not ok then
print("拷貝失敗:"..err)
end

-- 如需替換 /d/e/c,可在呼叫時指定覆蓋模式:
-- file_copy_into("/a/b/c", "/d/e/", "overwrite")

注:上述程式碼使用了 file.exists、file.path.last_component 和 file.path.add_component。