使用 PowerShell 移轉至 SharePoint

本文介紹基於 SharePoint 遷移工具 (SPMT) 遷移引擎的 PowerShell 指令小程式。它們可以用來將檔案從 SharePoint Server 本地的文件函式庫、清單項目及檔案分享轉移到 Microsoft 365。有關所有與 SharePoint 遷移相關的現有 PowerShell 指令匣資訊，請參閱 Microsoft SharePoint 遷移工具 cmdlet 參考資料。

PowerShell Cmdlet 提供與 SharePoint 移轉工具相同的功能。

注意事項

目前這些 PowerShell 指令檔尚未提供給中國 21Vianet 運營的 Office 365 用戶。

系統需求

最佳效能的建議需求

描述	建議
CPU	64位元四核心處理器或更佳處理器
RAM	16 GB
本機儲存空間	硬碟：150 GB 的可用空間
作業系統	Windows Server 2025 Standard 或 DatacenterWindows Server 2022 Standard 或 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 可轉散發套件	OneNote 移轉需求

重要事項

支援最多 400 字元的檔案路徑遷移，必須安裝 PowerShell 5.0x 與 .NET Framework 4.6.2 或以上版本。

最低需求 (效能較低)

描述	基本需求
CPU	64 位元 1.4 GHz 雙核心或更高等級處理器
RAM	8 GB
本機儲存空間	硬碟：150 GB 的可用空間
網路卡	高速網際網路連線
作業系統	Windows Server 2008 R2 或 2012 Windows 7、8 或 8.1 .NET Framework 4.6.2
Microsoft Visual C++ 2015 可轉散發套件	OneNote 移轉需求。
PowerShell	PowerShell 5.x 需要支援最多 400 字元的檔案路徑遷移。 PowerShell 6.0 或更高版本不支援。

解決長路徑問題的權宜之計

使用 SPMT PowerShell 時，可能會遇到路徑超過 260 字元的原始檔案掃描失敗。為了解決這個問題，你可以修改系統登錄檔，讓 PowerShell 能讀取長路徑檔案。

開啟 登錄編輯器，導向 "Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework"，新增一個鍵 "AppContext"。然後在鍵值下方加上兩個字串值。

價值名稱： Switch.System.IO.BlockLongPaths 價值資料： false
價值名稱： Switch.System.IO.UseLegacyPathHandling 價值資料： false

開始之前

用現有的 Active Directory 或其他新增帳號的選項來配置你的 Microsoft 365 Microsoft 365。欲了解更多資訊，請參閱 Microsoft 365 與本地環境的整合，以及新增使用者至 Microsoft 365 Apps 商務版。
打開資料夾： $env:UserProfile\Documents\WindowsPowerShell\Modules\Microsoft.SharePoint.MigrationTool.PowerShell。 確保裡面有DLLs。如果你使用 OneDrive，你需要將 WindowsPowershell 資料夾複製到 $env:UserProfile\OneDrive - Microsoft\Documents。

從此處執行以下 PowerShell 指令：

Import-Module Microsoft.SharePoint.MigrationTool.PowerShell

建立和初始化移轉工作階段

Register-SPMTMigration

此指令子會建立並初始化一個遷移會話。初始化是在會話層級配置遷移設定。若未定義特定設定參數，則使用預設設定。註冊一個會話後，你可以將任務加入該會話並開始遷移。

新增移轉工作

Add-SPMTTask

使用此 cmdlet 將新的遷移任務加入註冊的遷移會話。目前允許三種不同類型的任務：檔案分享任務、SharePoint 任務，以及 JSON 定義的任務。

注意：不允許重複任務。

移除工作

Remove-SPMTTask

使用此 Cmdlet 從註冊的移轉中移除現有的移轉工作。

開始移轉

Start-SPMTMigration

此指令小程式啟動註冊的 SPMT 遷移。

傳回目前工作階段的物件

Get-SPMTMigration

回傳當前會話的物件。此指令長包含當前任務狀態及當前會話層級設定。目前任務狀態包括：

S - 掃描檔案數量

已移轉檔案的數目
- 任何移轉錯誤訊息

停止目前的移轉

Stop-SPMTMigration

此指令小子取消目前的遷移。

在主控台中顯示移轉狀態詳細資料

Show-SPMTMigration

如果你以 NoShow 模式開始遷移，執行 Show-SPMTMigration 指令檔會在主控台顯示任務 ID、資料來源位置、目標位置及遷移狀態。選擇 Ctrl+C 後，顯示會回到 NoShow 模式。

移除移轉工作階段

Unregister-SPMTMigration

使用此 Cmdlet 刪除移轉工作階段。

範例案例

範例一： 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

範例二： IT 管理員希望將遷移從背景的「NoShow 模式」帶到前景，並執行以下 cmdlet，讓遷移進度在主控台中顯示。

Show-SPMTMigration

範例三：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-07-01