Copy-Item

Copy-Item
    [-Path] <String[]>
    [[-Destination] <String>]
    [-Container]
    [-Force]
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <PSCredential>]
    [-WhatIf]
    [-Confirm]
    [-FromSession <PSSession>]
    [-ToSession <PSSession>]
    [<CommonParameters>]

Copy-Item
    [[-Destination] <String>]
    -LiteralPath <String[]>
    [-Container]
    [-Force]
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <PSCredential>]
    [-WhatIf]
    [-Confirm]
    [-FromSession <PSSession>]
    [-ToSession <PSSession>]
    [<CommonParameters>]

Copy-Item
    [-Path] <string[]>
    [[-Destination] <string>]
    [-Container]
    [-Force]
    [-Filter <string>]
    [-Include <string[]>]
    [-Exclude <string[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <pscredential>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Copy-Item
    [[-Destination] <string>]
    -LiteralPath <string[]>
    [-Container]
    [-Force]
    [-Filter <string>]
    [-Include <string[]>]
    [-Exclude <string[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <pscredential>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Copy-Item cmdlet 将项从一个位置复制到同一命名空间中的另一个位置。 例如，它可以将文件复制到文件夹，但无法将文件复制到证书驱动器。

此 cmdlet 不会剪切或删除正在复制的项。 cmdlet 可以复制的特定项取决于公开该项的 PowerShell 提供程序。 例如，它可以复制文件系统驱动器中的文件和目录以及注册表驱动器中的注册表项和条目。

此 cmdlet 可以复制和重命名同一命令中的项。 若要重命名项，请在 Destination 参数的值中输入新名称。 若要重命名项而不复制它，请使用 Rename-Item cmdlet。

此示例将 mar1604.log.txt 文件复制到 C:\Presentation 目录。 不会删除原始文件。

Copy-Item "C:\Wabash\Logfiles\mar1604.log.txt" -Destination "C:\Presentation"

此示例将 C:\Logfiles 目录的内容复制到现有 C:\Drawings 目录中。 不会复制 Logfiles 目录。

如果 Logfiles 目录包含子目录中的文件，则这些子目录会随文件树一起复制。 默认情况下，容器 参数设置为 True，这将保留目录结构。

Copy-Item -Path "C:\Logfiles\*" -Destination "C:\Drawings" -Recurse

此示例复制 C:\Logfiles 源目录的内容并创建新的目标目录。 新的目标目录，\Logs 是在 C:\Drawings中创建的。

若要包含源目录的名称，请复制到现有目标目录，如 示例 2所示。 或者，将新目标目录命名为与源目录相同的目录。

Copy-Item -Path "C:\Logfiles" -Destination "C:\Drawings\Logs" -Recurse

此示例使用 Copy-Item cmdlet 将 Get-Widget.ps1 脚本从 \\Server01\Share 目录复制到 \\Server12\ScriptArchive 目录。 作为复制作的一部分，该命令将项名称从 Get-Widget.ps1 更改为 Get-Widget.ps1.txt，以便可以安全地附加到电子邮件。

$copyParams = @{
    Path        = "\\Server01\Share\Get-Widget.ps1"
    Destination = "\\Server12\ScriptArchive\Get-Widget.ps1.txt"
}
Copy-Item @copyParams

使用 凭据创建名为 server01 的远程计算机，并将结果存储在名为 的变量中。

Copy-Item cmdlet 使用存储在 test.log 变量中的会话信息，将 D:\Folder001 从 C:\Folder001_Copy 文件夹复制到远程计算机上的 $Session 文件夹。 不会删除原始文件。

$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
Copy-Item "D:\Folder001\test.log" -Destination "C:\Folder001_Copy\" -ToSession $Session

使用 凭据创建名为 server01 的远程计算机，并将结果存储在名为 的变量中。

Copy-Item cmdlet 使用存储在 D:\Folder002 变量中的会话信息将 C:\Folder002_Copy 文件夹复制到远程计算机上的 $Session 目录。 如果不使用 Recurse 开关，则不会复制任何子文件夹或文件。 该作将创建 Folder002_Copy 文件夹（如果尚不存在）。

$Session = New-PSSession -ComputerName "Server02" -Credential "Contoso\User01"
Copy-Item "D:\Folder002\" -Destination "C:\Folder002_Copy\" -ToSession $Session

使用 凭据创建名为 server01 的远程计算机，并将结果存储在名为 的变量中。

Copy-Item cmdlet 使用存储在 D:\Folder003 变量中的会话信息将 C:\Folder003_Copy 文件夹中的整个内容复制到远程计算机上的 $Session 目录。 子文件夹随文件树一起复制。 该作将创建 Folder003_Copy 文件夹（如果尚不存在）。

$Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\User01"
Copy-Item "D:\Folder003\" -Destination "C:\Folder003_Copy\" -ToSession $Session -Recurse

使用 凭据创建名为 server01 的远程计算机，并将结果存储在名为 的变量中。

Copy-Item cmdlet 使用存储在 scriptingexample.ps1 变量中的会话信息，将 D:\Folder004 从 C:\Folder004_Copy 文件夹复制到远程计算机上的 $Session 文件夹。 不会删除原始文件。

$Session = New-PSSession -ComputerName "Server04" -Credential "Contoso\User01"
$copyParams = @{
    Path        = "D:\Folder004\scriptingexample.ps1"
    Destination = "C:\Folder004_Copy\scriptingexample_copy.ps1"
    ToSession   = $Session
}
Copy-Item @copyParams

使用 凭据创建名为 server01 的远程计算机，并将结果存储在名为 的变量中。

Copy-Item cmdlet 使用存储在 test.log 变量中的会话信息将远程 C:\MyRemoteData\D:\MyLocalData 复制到本地 $Session 文件夹。 不会删除原始文件。

$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
Copy-Item "C:\MyRemoteData\test.log" -Destination "D:\MyLocalData\" -FromSession $Session

使用 凭据创建名为 server01 的远程计算机，并将结果存储在名为 的变量中。

Copy-Item cmdlet 使用存储在 C:\MyRemoteData\scripts 变量中的会话信息将远程 D:\MyLocalData 文件夹中的整个内容复制到本地 $Session 文件夹。 如果脚本文件夹包含子文件夹中的文件，则这些子文件夹会随文件树一起复制。

$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
Copy-Item "C:\MyRemoteData\scripts" -Destination "D:\MyLocalData\" -FromSession $Session

使用 凭据创建名为 server01 的远程计算机，并将结果存储在名为 的变量中。

Copy-Item cmdlet 使用存储在 C:\MyRemoteData\scripts 变量中的会话信息将远程 D:\MyLocalData\scripts 文件夹中的整个内容复制到本地 $Session 文件夹。 由于使用了 Recurse 参数，因此该操作会创建脚本文件夹（如果尚不存在）。 如果脚本文件夹包含子文件夹中的文件，则这些子文件夹会随文件树一起复制。

$Session = New-PSSession -ComputerName "Server01" -Credential "Contoso\User01"
$copyParams = @{
    Path        = "C:\MyRemoteData\scripts"
    Destination = "D:\MyLocalData\scripts"
    FromSession = $Session
    Recurse     = $true
}
Copy-Item @copyParams

此示例演示如何将文件从多级文件夹结构复制到单个平面文件夹中。 前三个命令显示现有文件夹结构和两个文件的内容，两个文件的名称 file3.txt。

PS C:\temp\test> (Get-ChildItem C:\temp\tree -Recurse).FullName
C:\temp\tree\subfolder
C:\temp\tree\file1.txt
C:\temp\tree\file2.txt
C:\temp\tree\file3.txt
C:\temp\tree\subfolder\file3.txt
C:\temp\tree\subfolder\file4.txt
C:\temp\tree\subfolder\file5.txt

PS C:\temp\test> Get-Content C:\temp\tree\file3.txt
This is file3.txt in the root folder

PS C:\temp\test> Get-Content C:\temp\tree\subfolder\file3.txt
This is file3.txt in the subfolder

PS C:\temp\test> Copy-Item -Path C:\temp\tree -Filter *.txt -Recurse -Container:$false
PS C:\temp\test> (Get-ChildItem . -Recurse).FullName
C:\temp\test\subfolder
C:\temp\test\file1.txt
C:\temp\test\file2.txt
C:\temp\test\file3.txt
C:\temp\test\file4.txt
C:\temp\test\file5.txt

PS C:\temp\test> Get-Content .\file3.txt
This is file3.txt in the subfolder

Copy-Item cmdlet 将 容器 参数设置为 $false。 这会导致复制源文件夹的内容，但不保留文件夹结构。 请注意，目标文件夹中覆盖同名的文件。

此示例显示使用 Include 参数选择要复制的项的结果。

此示例使用以下包含要复制的文件的文件夹结构：

• D:\temp\tree\example.ps1
• D:\temp\tree\example.txt
• D:\temp\tree\examples\
• D:\temp\tree\examples\example_1.txt
• D:\temp\tree\examples\example_2.txt
• D:\temp\tree\examples\subfolder\
• D:\temp\tree\examples\subfolder\test.txt

在此示例中，Copy-Item 使用通配符为 Path 和 Include 参数调用。 为 Path 参数指定通配符可确保它处理匹配 D:\temp\tree\*的所有文件和文件夹。 Include 参数筛选要处理的项列表，将作限制为仅以 ex开头的路径。

PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex*
PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName
D:\temp\out\examples
D:\temp\out\example.ps1
D:\temp\out\example.txt

Include 参数应用于 D:\temp\tree 文件夹的内容，以复制与 ex*匹配的所有项目。 请注意，在没有递归的情况下，将复制 D:\temp\out\examples 文件夹，但不会复制其内容。

此示例显示使用 Include 参数选择要复制的项的结果。

此示例使用以下包含要复制的文件的文件夹结构：

• D:\temp\tree\example.ps1
• D:\temp\tree\example.txt
• D:\temp\tree\examples\
• D:\temp\tree\examples\example_1.txt
• D:\temp\tree\examples\example_2.txt
• D:\temp\tree\examples\subfolder\
• D:\temp\tree\examples\subfolder\test.txt

在此示例中，Copy-Item 使用通配符为 Path 和 Include 参数调用。 为 Path 参数指定通配符可确保它处理匹配 D:\temp\tree\*的所有文件和文件夹。 Include 参数筛选要处理的项列表，将作限制为仅以 ex开头的路径。

D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse
D:\temp\out> (Get-ChildItem -Recurse).FullName
D:\temp\out\examples
D:\temp\out\example.ps1
D:\temp\out\example.txt
D:\temp\out\examples\subfolder
D:\temp\out\examples\example_1.txt
D:\temp\out\examples\example_2.txt
D:\temp\out\examples\subfolder\test.txt

Include 参数应用于 D:\temp\tree 文件夹的内容，以复制与 ex*匹配的所有项目。 请注意，随着递归，D:\temp\out\examples 文件夹随所有文件和子文件夹一起复制。 该副本包含 不 与 include 筛选器匹配的文件。 使用 Copy-Item时，筛选器仅适用于由 Path 参数指定的顶级。 然后，递归应用于这些匹配项。

此示例演示如何限制从通配符匹配路径递归复制到另一个文件夹中的文件。 示例 13 显示，由于 Include 参数仅筛选为通配符指定路径 解析的路径，因此 Include 参数不能用于限制从文件夹中递归复制的文件。 相反，可以使用 Get-ChildItem 查找要复制的项，并将这些项目传递给 Copy-Item。

此示例使用以下包含要复制的文件的文件夹结构：

• D:\temp\tree\example.ps1
• D:\temp\tree\example.txt
• D:\temp\tree\examples\
• D:\temp\tree\examples\example_1.txt
• D:\temp\tree\examples\example_2.txt
• D:\temp\tree\examples\subfolder\
• D:\temp\tree\examples\subfolder\test.txt

若要复制以 ex*开头的所有项，请将 Get-ChildItem 与 Recurse 和 Filter 参数一起使用，并将结果通过管道传递给 Copy-Item。

D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item
D:\temp\out> (Get-ChildItem -Recurse).FullName
D:\temp\out\examples
D:\temp\out\example_1.txt
D:\temp\out\example_2.txt
D:\temp\out\example.ps1
D:\temp\out\example.txt

与 Copy-Item不同，用于 的 Get-ChildItem 参数适用于在递归期间发现的项。 这使你可以以递归方式查找、筛选和复制项。

此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 有关详细信息，请参阅 about_CommonParameters。

可以通过管道将包含路径的字符串传递给此 cmdlet。

默认情况下，此 cmdlet 不返回任何输出。

使用 PassThru 参数时，此 cmdlet 返回一个表示复制项的对象。

PowerShell 包含以下与 Copy-Item相关的别名：

• 所有平台：
  • copy
  • cpi
• 窗户：
  • cp

此 cmdlet 的设计目的是与任何供应商公开的数据进行协作。 若要列出会话中可用的提供程序，请键入 Get-PSProvider。 有关详细信息，请参阅 about_Providers。