使用 Amazon S3 做為 PowerShell 磁碟機

適用於：5.0.288 AWS.Tools.S3 及更新版本。S3 磁碟機提供者及其 cmdlet 隨附於 AWS.Tools.S3模組，在 Windows PowerShell 5.1 和 PowerShell 7+ (Windows、Linux、macOS) 上執行。

S3 PowerShell 磁碟機可讓您將 Amazon S3 儲存體掛載為磁碟機，並使用它的方式與使用本機磁碟的方式相同。掛載磁碟機之後，供應商會將儲存貯體和字首顯示為資料夾，並將物件顯示為檔案。常見的導覽命令可直接針對 S3 運作，包括 Set-Location、Get-ChildItem、Set-Content、 Get-Content和 Remove-Item。

本主題涵蓋安裝、掛載、導覽、傳輸內容和卸載，以及 S3 磁碟機的登入資料、區域和安全行為。

先決條件

匯入模組會註冊名為 的 PowerShell 供應商AWS.S3。您可以確認它是否可用：

Get-PSProvider AWS.S3

掛載磁碟機

使用 Mount-S3PSDrive建立磁碟機。-Name 參數會成為每個路徑中的磁碟機名稱 （例如， -Name S3 為您提供類似 的路徑S3:/amzn-s3-demo-bucket/reports/index.txt)。

# Mount an S3: drive using a named profile and Region
Mount-S3PSDrive -Name S3 -ProfileName my-profile -Region us-east-1
# List buckets
Get-ChildItem S3:/

輸出範例：

   Type     LastModified              Size Name
   ----     ------------              ---- ----
   Bucket   2026-06-02 09:14:03            amzn-s3-demo-app-logs
   Bucket   2026-01-08 16:47:51            amzn-s3-demo-reports

如果您已使用 Set-AWSCredential和 設定工作階段預設值Set-DefaultAWSRegion，則可以在沒有其他參數的情況下掛載 ：

Set-AWSCredential -ProfileName my-profile
Set-DefaultAWSRegion us-west-2
Mount-S3PSDrive -Name S3

Mount-S3PSDrive 是 PowerShell 內建 上的薄包裝函式New-PSDrive。如果您願意，可以直接建立磁碟機並傳遞相同的登入資料和區域參數：

New-PSDrive -Name S3 -PSProvider AWS.S3 -Root '' -Scope Global -ProfileName my-profile -Region us-east-1

根據預設， 不會Mount-S3PSDrive產生輸出。-PassThru 如果您想要傳回PSDriveInfo物件，請新增 。

如何解決登入資料和區域

S3 磁碟機會驗證並選取與 S3 cmdlet 完全相同的區域：先明確參數，然後工作階段預設由 Set-AWSCredential和 設定Set-DefaultAWSRegion，然後是 SDK 預設鏈結的設定檔、環境和執行個體中繼資料來源。如需完整的解析度順序，請參閱 使用 AWS 登入資料和 指定 AWS 的區域 AWS Tools for PowerShell。

如果沒有提供區域，則磁碟機會回復為 us-east-1。您使用 掛載的區域只是起始區域：單一磁碟機可以跨區域到達儲存貯體 （請參閱 從單一磁碟機跨區域存取儲存貯體)。

錯誤描述檔或缺少儲存貯體或字首會在 失敗Mount-S3PSDrive。在您存取 物件之前，可能不會出現某些許可錯誤。

像本機磁碟機一樣導覽 Amazon S3

掛載磁碟機之後，請使用常見的 PowerShell 磁碟機命令進行導覽。S3 沒有真正的資料夾，但提供者會將字首顯示為資料夾，以便您以相同的方式導覽它們。

# Change into a bucket, then a prefix
Set-Location S3:/amzn-s3-demo-reports/2026
# List the current location
Get-ChildItem

輸出範例：

   Type     LastModified              Size Name
   ----     ------------              ---- ----
   Folder                                  q1
   Folder                                  q2
   Object   2026-03-31 18:02:11      48210 summary.txt

# List a path without changing location
Get-ChildItem S3:/amzn-s3-demo-bucket/reports/2026

標籤完成適用於儲存貯體、字首和物件，因此您可以完成路徑，而無需輸入完整名稱。

Get-ChildItem 會將每個項目傳回為公開 Name、Size、 Type和 LastModified 屬性的物件。這些屬性可讓 將管道直接列出至 Where-Object和 等命令Sort-Object。 Type是 Bucket、 Folder或 之一Object。資料夾和儲存貯體不帶任何大小。

# List the 10 largest objects with the prefix "2026"
Get-ChildItem S3:/amzn-s3-demo-app-logs/2026 -Recurse |
    Where-Object Type -eq 'Object' |
    Sort-Object Size -Descending |
    Select-Object -First 10 Name, Size, LastModified

其他導覽命令也適用於磁碟機：

# Retrieve the single item at an exact path (no children)
Get-Item S3:/amzn-s3-demo-bucket/reports/index.txt
# Test whether a path exists and whether it is a folder or an object
Test-Path S3:/amzn-s3-demo-bucket/reports                              # -> True
Test-Path S3:/amzn-s3-demo-bucket/reports -PathType Container          # -> True (a prefix)
Test-Path S3:/amzn-s3-demo-bucket/reports/index.txt -PathType Leaf     # -> True (an object)

使用 時-Recurse，項目的 Name 是相對於字首的索引鍵 （因此可以包含 /)，相同的分葉名稱可以顯示在不同的字首下。當您需要明確識別列出的項目時 （例如，若要將其往前輸送），請使用其 PSPath而非 Name。

# Read each listed object by explicit PSPath
Get-ChildItem S3:/amzn-s3-demo-bucket/prefix | ForEach-Object {
    Get-Content -LiteralPath $_.PSPath -AsByteStream -Raw
}

Get-Content -LiteralPath 'S3:/amzn-s3-demo-bucket/data[2026].csv' -Raw

從 S3 讀取物件

Get-Content 會下載 物件。根據預設，它會逐行傳回文字。新增 -Raw 以將整個物件傳回為單一字串。Get-Content 和 -AsByteStream 都Set-Content支援-Encoding文字和二進位內容。

# Read an object line by line
Get-Content S3:/amzn-s3-demo-reports/2026/summary.txt
# Read the whole object as one string
Get-Content S3:/amzn-s3-demo-reports/2026/summary.txt -Raw

對於非文字物件，請使用 -AsByteStream 取得原始位元組。在 S3 路徑上，這適用於 PowerShell 7+ 和 Windows PowerShell 5.1，因為 S3 提供者提供 參數。只有本機檔案會因版本而有所不同 （請參閱 讀取本機檔案位元組因版本而異)。若要控制文字解碼，-Encoding請使用任何標準 PowerShell 編碼名稱 UTF8BOM(UTF8、ASCII、、 等） 來新增 Unicode。Get-Content 和 上的預設值都是沒有 BOM 的 UTF-8Set-Content。

# Read raw bytes
Get-Content S3:/amzn-s3-demo-bucket/images/logo.png -AsByteStream -Raw
# Decode as a specific text encoding
Get-Content S3:/amzn-s3-demo-bucket/data/report.csv -Encoding UTF8

Get-Content 也接受-PartSize設定 S3 最小值為 5 MiB 到最大值為 5 GiB 之間的分段下載部分大小，以位元組為單位。它在 -PartSize上鏡像Set-Content，這會設定上傳組件大小 （請參閱 上傳非常大的物件)。

$bytes = [byte[]]((Get-Content S3:/amzn-s3-demo-bucket/images/logo.png -AsByteStream -Raw) | ForEach-Object { $_ })

將物件寫入 S3

Set-Content 會上傳 （並覆寫） 物件。

# Write text
Set-Content S3:/amzn-s3-demo-reports/2026/notes.txt -Value 'Draft complete'
# Write several lines
Set-Content S3:/amzn-s3-demo-bucket/notes/list.txt -Value @('alpha', 'beta', 'gamma')
# Write raw bytes
Set-Content S3:/amzn-s3-demo-bucket/images/logo.png -AsByteStream -Value $bytes

上傳有下列選項：

您可以隨時使用 Ctrl+C 取消上傳。 在上傳完成之前，不會遞交任何內容，因此取消不會保留半寫入物件來取代舊物件。

上傳非常大的物件

每次透過磁碟機上傳都是分段上傳，而 S3 會將分段上傳限制為 10，000 個組件。預設部分大小為 5 MiB，以大約 48 GiB 為上限，超過上限的上傳會用盡部分且失敗。若要上傳更大的內容，請提高 ，-PartSize使其至少為 object size / 10,000：

# Upload a ~200 GiB object with 64 MiB parts (200 GiB / 10,000 = 21 MiB, so 64 MiB is plenty)

# PowerShell 7+
Get-Content ./huge.bin -AsByteStream -ReadCount 8MB |
    Set-Content S3:/amzn-s3-demo-bucket/archive/huge.bin -AsByteStream -PartSize 64MB

# Windows PowerShell 5.1 (local read uses -Encoding Byte; the S3 write keeps -AsByteStream -PartSize)
Get-Content ./huge.bin -Encoding Byte -ReadCount 8MB |
    Set-Content S3:/amzn-s3-demo-bucket/archive/huge.bin -AsByteStream -PartSize 64MB

-PartSize 和 -StorageClass是 S3 目的地參數。使用它們搭配明確的 S3 目的地路徑 （如上述範例所示），而非管道繫結目的地物件。

-PartSize 接受介於 S3 最小值 5 MiB 與最大值 5 GiB 之間的值。在最大 5 GiB 的情況下，10，000 個組件涵蓋 S3 支援的最大物件 (5 TiB)。

在 S3 和本機磁碟之間複製物件

Copy-Item 不支援使用 在 S3 內複製 （請參閱 支援和不支援的操作)。若要在本機磁碟和 S3 之間移動資料，請透過 Get-Content和 輸送內容Set-Content。

對於二進位資料，請完全讀取和寫入位元組。S3 路徑在兩個 PowerShell 版本-AsByteStream上使用 ；只有本機端不同，如中所述讀取本機檔案位元組因版本而異。

# Upload a local file (PowerShell 7+; on Windows PowerShell 5.1 the local read uses -Encoding Byte)
Get-Content ./report.csv -AsByteStream -ReadCount 8MB | Set-Content S3:/amzn-s3-demo-bucket/data/report.csv -AsByteStream

# Download to a local file (on Windows PowerShell 5.1 the local write uses -Encoding Byte)
Get-Content S3:/amzn-s3-demo-bucket/data/report.csv -AsByteStream | Set-Content ./report.csv -AsByteStream

讀取本機檔案位元組因版本而異

針對本機檔案使用 PowerShell 的內建 FileSystem 提供者，且該提供者在 Windows PowerShell 5.1 -AsByteStream 中沒有 （送達 PowerShell 6)。請改用 -Encoding Byte 。這是 5.1 的限制，而不是 S3 磁碟機控制的內容；S3 路徑-AsByteStream採用兩種版本。

對於伺服器端 S3-to-S3複本，請使用 Copy-S3Object cmdlet。

刪除物件和字首

Remove-Item 會刪除單一物件。刪除字首 （包含內容的資料夾） 需要 -Recurse，這會批次移除其下的所有項目。

# Delete a single object
Remove-Item S3:/amzn-s3-demo-bucket/notes/todo.txt
# Delete a prefix and everything under it
Remove-Item S3:/amzn-s3-demo-bucket/old-logs -Recurse

Remove-Item 提示是否取決於您的目標：

使用原生 PowerShell 切換來預覽或鎖定刪除：

# Preview without deleting
Remove-Item S3:/amzn-s3-demo-bucket/old-logs -Recurse -WhatIf
# Ask for confirmation
Remove-Item S3:/amzn-s3-demo-bucket/notes/todo.txt -Confirm

您無法透過磁碟機刪除整個儲存貯體，因為儲存貯體生命週期操作超出範圍。請改用 Remove-S3Bucket。

將磁碟機範圍調整為一個儲存貯體或字首

使用 掛載，-Root將磁碟機限制在儲存貯體，或儲存貯體中的字首。然後，磁碟機的根是該位置，而導覽會限制在它的下方。

# Mount rooted at a bucket: the drive root lists the bucket's top-level entries
Mount-S3PSDrive -Name Data -Root amzn-s3-demo-bucket -ProfileName my-profile -Region us-east-1
Get-ChildItem Data:/                 # top-level keys in amzn-s3-demo-bucket
Get-Content Data:/reports/index.txt  # -> amzn-s3-demo-bucket/reports/index.txt

# Mount rooted at a bucket + prefix
Mount-S3PSDrive -Name Reports -Root amzn-s3-demo-reports/2026 -ProfileName my-profile -Region us-east-1
Get-ChildItem Reports:/              # contents of amzn-s3-demo-reports/2026/

根必須已存在。不存在的儲存貯體或字首會失敗掛載。由於相對路徑無法爬過根目錄 (.. 被引擎封鎖），因此範圍掛載可讓您集中檢視一個專案的資料。

從單一磁碟機跨區域存取儲存貯體

單一掛載的磁碟機可以跨區域到達儲存貯體。第一次接觸儲存貯體時，供應商會查詢其區域，並自動將後續呼叫路由至正確的端點。每個區域不需要個別的磁碟機。

# Mounted in us-east-1, but this bucket is in us-west-2 and commands work without extra configuration
Mount-S3PSDrive -Name S3 -ProfileName my-profile -Region us-east-1
Get-ChildItem S3:/amzn-s3-demo-west-bucket
Get-Content   S3:/amzn-s3-demo-west-bucket/data/report.csv -Raw

設定預設儲存類別

使用 在掛載時間設定全磁碟機的預設儲存體方案-StorageClass。每次透過該磁碟機上傳都會使用指定的類別，除非特定 以自己的 Set-Content覆寫它-StorageClass。

# Set all uploads to default to STANDARD_IA
Mount-S3PSDrive -Name Archive -ProfileName my-profile -Region us-east-1 -StorageClass STANDARD_IA
Set-Content Archive:/amzn-s3-demo-bucket/cold/data.txt -Value '...'                        # STANDARD_IA
Set-Content Archive:/amzn-s3-demo-bucket/hot/data.txt  -Value '...' -StorageClass STANDARD # overrides to STANDARD

卸載磁碟機

使用 Dismount-S3PSDrive( 上的包裝函式Remove-PSDrive) 移除磁碟機。先變更為另一個位置，因為 PowerShell 不會移除目前位置的磁碟機。

Set-Location $HOME           # or C:\ on Windows
Dismount-S3PSDrive -Name S3

支援和不支援的操作

使用 磁碟機瀏覽和移動物件內容。儲存貯體生命週期和伺服器端複製操作會保留專用 S3 cmdlet。

支援

不支援

不支援的命令失敗，其中的訊息會命名命令並指向替代 - 例如，「S3 磁碟機不支援複製項目。使用 Copy-S3Object 或管道 Get-Content 來設定內容。」 這些*-ItemProperty命令是例外狀況，如上表所述。

命令參考

如需 Mount-S3PSDrive 和 Dismount-S3PSDrive 的完整參數清單，請參閱 AWS Tools for PowerShell Cmdlet 參考。

在 S3 路徑上，磁碟機也會將動態參數新增至 Set-Content ，Get-Content且這些 cmdlet 的 PowerShell 文件不會涵蓋：

疑難排解

「無法卸載磁碟機，因為它正在使用中。」

S3 磁碟機是目前的位置。變更為另一個磁碟機上的位置，例如 $HOME，然後Dismount-S3PSDrive再次執行。

掛載失敗並顯示「找不到根或無法連線」。

中的儲存貯體或字首-Root不存在。檢查名稱 （以及 區域，如果儲存貯體位於您的登入資料不預設的儲存貯體中）。登入資料失敗會產生不同的錯誤，而不是此「無法連線」訊息。在您存取物件之前，根目錄上的許可錯誤可能不會出現，因此成功掛載並不保證您可以讀取其中的每個路徑。

刪除非空白字首會在指令碼中懸置。

當您刪除沒有 的非空白字首時，就會發生這種情況-Recurse。PowerShell 引擎會引發確認提示，因為字首有子系 （檔案系統提供者的 container-has-children 行為）。非互動式主機無法回答提示，因此命令會封鎖。

傳遞 -Recurse 以刪除字首的內容而不提示，或以互動方式確認以繼續。 (-Force 不會由磁碟機的刪除路徑查閱，因此不會在此產生任何影響。)

「我剛在磁碟機外部變更的物件仍會顯示舊清單。」

清單會短暫快取 （大約一秒鐘），以保持快速導覽。透過磁碟機所做的變更會立即顯示。由其他工具所做的變更會在短快取過期後顯示。

「金鑰包含反斜線。」

磁碟機是否可以定址包含反斜線的金鑰取決於作業系統，因為磁碟機接受平台的原生路徑分隔符號：