使用 Amazon S3 作为 PowerShell 驱动器

适用于：AWS.Tools.S35.0.288 及更高版本。S3 驱动器提供商及其 cmdlet 包含在该模块中，该AWS.Tools.S3模块在 Windows PowerShell 5.1 和 PowerShell 7+（Windows、Linux、macOS）上运行。

S3 PowerShell 驱动器允许您将 Amazon S3 存储作为驱动器挂载，并像使用本地磁盘一样使用它。安装驱动器后，提供商将存储桶和前缀显示为文件夹，将对象显示为文件。常见的导航命令直接针对 S3 起作用Set-Location，包括Get-ChildItemGet-Content、、Set-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 默认链的配置文件、环境和实例元数据源。有关完整分辨率顺序，请参阅使用 Amazon 凭证和为... 指定 Amazon 区域 Amazon 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、TypeSize、和LastModified属性的对象返回。这些属性允许清单直接传送到诸如Where-Object和之类的命令中Sort-Object。Type是BucketFolder、或之一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-ContentSet-Content-Encoding支持文本和二进-AsByteStream制内容。

# 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 编码名称（UTF8UTF8BOM、Unicode、ASCII、等）。默认情况下，Get-Content和都 UTF-8 没有 BOM Set-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 之间设置分段下载分段大小（以字节为单位）。它会镜像 -PartSizeSet-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 和本地磁盘之间复制对象

不支持在 S3 中使用进行Copy-Item复制（请参阅支持和不支持的操作）。要在本地磁盘和 S3 之间移动数据，请将内容通过管道传送到Get-Content和Set-Content。

对于二进制数据，请精确读取和写入字节。两个 PowerShell 版本都使用 -AsByteStream S3 路径；只有本地端有所不同，如中所述读取本地文件字节因版本而异。

# 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 提供程序，而该提供程序-AsByteStream在 Windows PowerShell 5.1 中没有（它在 PowerShell 6 中推出）。改为-Encoding Byte在那里使用。这是 5.1 的限制，不是 S3 驱动器控制的；两个版本都采用 -AsByteStream S3 路径。

对于服务器端副 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。

将驱动器范围限制为一个存储桶或前缀

使用 mount -Root with 将驱动器限制在存储桶中，或者将前缀限制在存储桶内。因此，驱动器的根目录就是该位置，导航仅限于其下方。

# 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通过该驱动器进行的每次上传都使用指定的类，除非特定对象用自己的-StorageClass类Set-Content替换该类。

# 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。

支持

不支持

不支持的命令失败，并显示一条消息，该消息命名命令并指向替代命令，例如，“Copy-Item S3 驱动器不支持”。使用 Copy-S3Object，或 Get-Content 通过管道传送到 Set-Content。” 这些*-ItemProperty命令是例外，如上表所述。

命令参考

有关Mount-S3PSDrive和的完整参数列表 Dismount-S3PSDrive，请参阅 Amazon Tools for PowerShell Cmdlet 参考。

在 S3 路径上，驱动器还会添加动态参数Get-Content，Set-Content这些 cmdlet 的 PowerShell 文档未涵盖以下内容：

问题排查

“无法卸下驱动器，因为它正在使用中。”

S3 驱动器是当前位置。切换到其他驱动器上的某个位置$HOME，例如，然后Dismount-S3PSDrive再次运行。

装载失败，显示 “找不到根目录或无法访问根目录”。

中的存储桶或前缀-Root不存在。检查名称（如果存储桶位于您的证书未默认设置的存储桶中，则检查该区域）。凭据失败会产生不同的错误，而不是这条 “无法访问” 的消息。在您访问对象之前，根目录上的权限错误可能不会出现，因此挂载成功并不能保证您可以读取其下的所有路径。

删除非空前缀会在脚本中挂起。

当你删除不-Recurse带的非空前缀时，就会发生这种情况。引 PowerShell 擎会发出确认提示，因为前缀有子项（文件系统提供商的容器有子代行为）。非交互式主机无法应答提示符，因此该命令会阻塞。

传递-Recurse可在不提示的情况下删除前缀的内容，或通过交互方式确认继续。（-Force驱动器的删除路径未查询，因此此处无效。）

“我刚刚在驱动器外更改的对象仍显示旧清单。”

清单会短暂缓存（大约一秒钟），以保持快速导航。通过驱动器所做的更改会立即出现。其他工具所做的更改将在短缓存过期后出现。

“密钥包含反斜线。”

驱动器能否寻址包含反斜线的密钥取决于操作系统，因为该驱动器接受平台的本机路径分隔符：