使用 PowerShell 迁移到 SharePoint

本文介绍基于 SPMT (SPMT) 迁移引擎的 SharePoint 迁移工具的 PowerShell cmdlet。它们可用于将文件从 SharePoint 服务器本地文档库和列表项以及文件共享移动到 Microsoft 365。有关与 SharePoint 迁移相关的所有当前 PowerShell cmdlet 的信息，请参阅 Microsoft SharePoint 迁移工具 cmdlet 参考。

PowerShell cmdlet 的功能与 SharePoint 迁移工具相同。

注意

这些 PowerShell cmdlet 目前不适用于由世纪互联运营的 Office 365 用户。

系统要求

为实现最佳性能而建议满足的要求

说明	建议
CPU	64 位 4 核处理器或更高版本
RAM	16 GB
本地存储	硬盘：150GB 可用空间
操作系统	Windows Server 2025 Standard or DatacenterWindows Server 2022 Standard or DatacenterWindows Server 2019 Standard 或Datacenter Windows Server 2016 Standard 或 Datacenter Windows Server 2012 R2 Standard 或 Datacenter Windows 10或 11 客户端 .NET Framework 4.6.2
Microsoft Visual C++ 2015 Redistributable	OneNote 迁移所必需

重要

需要 PowerShell 5.0x 和 .NET Framework 4.6.2 或更高版本才能支持最多 400 个字符的文件路径的迁移。

最低要求（预期性能较差）

说明	最低要求
CPU	64 位 1.4 GHz 双核处理器或更高
RAM	8 GB
本地存储	硬盘：150 GB 可用空间
网卡	高速 Internet 连接
操作系统	Windows Server 2008 R2 或 2012 Windows 7、8 或 8.1 .NET Framework 4.6.2
Microsoft Visual C++ 2015 Redistributable	OneNote 迁移所必需。
PowerShell	需要 PowerShell 5.x 来支持最多 400 个字符的文件路径的迁移。不支持 PowerShell 6.0 或更高版本。

长路径问题的解决方法

使用 SPMT PowerShell 时，对路径超过 260 个字符的源文件可能会遇到扫描失败。若要解决此问题，可以修改系统注册表，使 PowerShell 能够读取长路径文件。

打开 注册编辑器，导航到 "Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework"，添加新键 "AppContext"。然后在键下添加 2 个字符串值。

值名称： Switch.System.IO.BlockLongPaths 值数据： false
值名称： Switch.System.IO.UseLegacyPathHandling 值数据： false

开始之前

使用现有 Active Directory 或用于向 Microsoft 365 添加帐户的其他选项之一预配 Microsoft 365。有关详细信息，请参阅 Microsoft 365 与本地环境的集成和将用户添加到 Microsoft 365 商业应用版。
打开文件夹： $env:UserProfile\Documents\WindowsPowerShell\Modules\Microsoft.SharePoint.MigrationTool.PowerShell. 确保其中有 DLL。如果使用的是 OneDrive，则需要将 WindowsPowershell 文件夹复制到 $env:UserProfile\OneDrive - Microsoft\Documents.

从此位置运行以下 PowerShell 命令：

Import-Module Microsoft.SharePoint.MigrationTool.PowerShell

创建和初始化迁移会话

Register-SPMTMigration

此 cmdlet 创建并初始化迁移会话。初始化在会话级别配置迁移设置。如果未定义特定的设置参数，则使用默认设置。注册会话后，您可以向会话添加任务并开始迁移。

添加迁移任务

Add-SPMTTask

使用此 cmdlet 向注册的迁移会话添加新的迁移任务。目前允许三种不同类型的任务：文件共享任务、SharePoint 任务和 JSON 定义任务。

注意：不允许重复任务。

删除任务

Remove-SPMTTask

此 cmdlet 可用于从已注册的迁移会话中删除现有迁移任务。

开始迁移

Start-SPMTMigration

此 cmdlet 启动已注册的 SPMT 迁移。

返回当前会话对象

Get-SPMTMigration

返回当前会话的对象。此 cmdlet 包括当前任务和当前会话级别设置的状态。当前任务状态包括：

已扫描文件数
已迁移文件数
任何迁移错误消息

停止当前迁移

Stop-SPMTMigration

此 cmdlet 取消当前迁移。

在控制台中显示迁移状态详细信息

Show-SPMTMigration

如果您在 NoShow 模式下开始迁移，则运行 Show-SPMTMigration cmdlet 会在控制台中显示任务 ID、数据源位置、目标位置和迁移状态。选择 Ctrl+C 将显示器返回到 NoShow 模式。

删除迁移会话

Unregister-SPMTMigration

此 cmdlet 可用于删除迁移会话。

示例应用场景

示例 1： IT 管理员添加 SharePoint 本地任务并在后台开始迁移。

#Define SharePoint 2013 data source#
$SourceSiteUrl = "http://YourOnPremSite/"
$OnPremUserName = "Yourcomputer\administrator"
$OnPremPassword = ConvertTo-SecureString -String "OnPremPassword" -AsPlainText -Force
$SPCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $OnPremUserName, $OnPremPassword
$SourceListName = "SourceListName"

#Define SharePoint target#
$SPOUrl = "https://contoso.sharepoint.com"
$UserName = "admin@contoso.onmicrosoft.com"
$PassWord = ConvertTo-SecureString -String "YourSPOPassword" -AsPlainText -Force
$SPOCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $UserName, $PassWord
$TargetListName = "TargetListName"

#Define File Share data source#
$FileshareSource = "YourFileShareDataSource"

#Import SPMT Migration Module#
Import-Module Microsoft.SharePoint.MigrationTool.PowerShell

#Register the SPMT session with SharePoint credentials#
Register-SPMTMigration -SPOCredential $SPOCredential -Force

#Add two tasks into the session. One is SharePoint migration task, and another is File Share migration task.#
Add-SPMTTask -SharePointSourceCredential $SPCredential -SharePointSourceSiteUrl $SourceSiteUrl  -TargetSiteUrl $SPOUrl -MigrateAll
Add-SPMTTask -FileShareSource $FileshareSource -TargetSiteUrl $SPOUrl -TargetList $TargetListName

#Start Migration in the console. #
Start-SPMTMigration

示例 2： IT 管理员希望将迁移从后台“NoShow 模式”引入前台，并运行以下 cmdlet，以便在控制台中显示迁移进度。

Show-SPMTMigration

示例 3：IT 管理员希望通过加载 .csv 文件来进行批量迁移。此示例中的示例文件是 SPMT.csv。

Load CSV;
$csvItems = import-csv "C:\spmt.csv" -Header c1,c2,c3,c4,c5,c6
ForEach ($item in $csvItems)
{
    Write-Host $item.c1
    Add-SPMTTask -FileShareSource $item.c1 -TargetSiteUrl $item.c4 -TargetList $item.c5 -TargetListRelativePath $item.c6
}

spmt.csv文件中定义了两个迁移任务。

D:\MigrationTest\Files\Average_1M\c,,,https://SPOSite.sharepoint.com,Documents,Test
C:\work\Powershell\negative,,,https://SPOSite.sharepoint.com/,Documents,DocLibrary_SubfolderName

通过加载一个JSON文件进行批量迁移的代码片段：

#Load JSON:
$jsonItems = Get-Content -Raw -Path  "C:\spmt.json" | ConvertFrom-Json
ForEach ($taskItem in $jsonItems.Tasks)
{
    $jsonString = ConvertTo-Json $taskItem -Depth 100
    Add-SPMTTask -JsonDefinition $jsonString -SharePointSourceCredential $onpremCredential
}

spmt.json文件中定义了三个迁移任务。

{
   "Tasks":[
      {
         "SourcePath":"http://On-prem/sites/test",
         "TargetPath":"https://YourSPO.sharepoint.com",
         "Items":{
            "Lists":[
               {
                  "SourceList":"list-01",
                  "TargetList":"list-01"
               }
            ],
            "SubSites":[

            ]
         }
      },
      {
         "SourcePath":"http://On-prem/sites/test",
         "TargetPath":"https://YourSPO.sharepoint.com",
         "Items":{
            "Lists":[
               {
                  "SourceList":"list-02",
                  "TargetList":"list-02"
               }
            ],
            "SubSites":[

            ]
         }
      },
      {
         "SourcePath":"http://On-prem/sites/test",
         "TargetPath":"https://YourSPO.sharepoint.com",
         "Items":{
            "Lists":[
               {
                  "SourceList":"doclib-01",
                  "TargetList":"doclib-01"
               }
            ],
            "SubSites":[

            ]
         }
      }
   ]
}

示例 4：显示迁移进度

这些示例展示如何显示迁移项目的进度。 Get-SPMTMigration 返回当前会话的对象它包括当前任务状态和当前会话级别设置。

当前任务的状态包括：

已扫描的文件计数。
已筛选出的文件的计数。
已迁移的文件的计数。
失败文件的计数。
当前任务的迁移进度 (0 ~ 100) 。
当前任务状态。
迁移错误消息（如果有）。


# Start migration in the background
Start-SPMTMigration -NoShow

# Get the object of current migration
$session = Get-SPMTMigration

# Query migration status every 5 seconds until migration is finished
while ($session.Status -ne "Finished")
{
Write-Host $session.Status

    # Query migration progress of each tasks
    Foreach ($taskStatus in $session.StatusOfTasks)
    {
        $taskStatus.MigratingProgressPercentage
}

    Start-Sleep -Seconds 5
}

反馈

此页面是否有帮助？

Last updated on 2026-08-20