前言

在日常开发中，我们经常会遇到一个需求：将当前项目的所有文件打包成一个压缩文件，同时希望能够像 git commit 一样，智能地忽略掉 .gitignore 文件中指定的那些临时文件、依赖库和构建产物。这个操作在持续集成（CI）或手动部署时非常有用。

听起来很简单，对吧？git 提供了列出文件的命令，PowerShell 提供了压缩命令，把它们组合起来不就行了？然而，当你的项目路径或文件名包含中文字符，并且你在 Windows 环境下操作时，一件看似简单的事情可能会演变成一场与编码和命令参数斗智斗勇的"踩坑之旅"。

本文将完整复盘这个过程，从最初的简单想法，到屡次碰壁，再到最终找到一个健壮、可靠的解决方案。

旅程起点：一个简单的想法

我们的目标很明确：压缩一个 Git 仓库里所有未被忽略的文件。这包括：

1. 已经被 Git 跟踪（tracked）的文件。
2. 未被跟踪（untracked），但也没有被 .gitignore 忽略的新文件。

Git 命令行工具为我们提供了获取这两类文件列表的方法：

• git ls-files：列出所有已跟踪的文件。
• git ls-files --others --exclude-standard：列出所有未被跟踪且未被忽略的文件。

PowerShell 中，我们可以用 + 来合并两个列表，然后用 Compress-Archive 命令来进行压缩。于是，我们的第一个命令诞生了：

# 方案一：天真的初次尝试
Compress-Archive -Path ((git ls-files) + (git ls-files --others --exclude-standard)) -DestinationPath "archive.zip"

然而，执行后，一个鲜红的错误无情地拍在了脸上：

Compress-Archive : 路径""Postman\346\265\213\350\257\225\346\226\207\344\273\266.zip""不存在...

第一次踩坑：Git 的"画蛇添足"与 PowerShell 的"一脸懵逼"

错误信息非常诡异。Postman测试文件.zip 这个文件名变成了一串带有八进制转义的乱码。

问题根源：git config core.quotepath

经过探查，我们发现这是 Git 的一个"保护机制"在作祟。当 git ls-files 在路径中检测到非 ASCII 字符或特殊符号时，为了保证输出的路径能被各种环境安全地解析，它默认会启用 core.quotepath 选项。这个选项会将路径用双引号包裹，并用 C 语言风格的八进制序列来转义特殊字符。

““Postman\346\265\213…”” 正是 Postman测试文件.zip 被转义后的结果。Git 的本意是好的，但它没料到 PowerShell 的 Compress-Archive 命令完全不认识这种"方言"，导致 PowerShell 拿着这个转义后的字符串去文件系统里找文件，结果自然是"查无此档"。

第二次尝试：换个姿势传递参数

我们想，既然直接拼接字符串有问题，那用 PowerShell 更优雅的管道（|）来传递参数会不会好一点？管道在处理流式数据时通常更稳定。

# 方案二：尝试使用管道
(git ls-files) + (git ls-files --others --exclude-standard) | Compress-Archive -DestinationPath "archive.zip" -Force

结果…完全相同的错误。这证明问题不在于参数是如何传递的，而在于传递的内容本身就是错误的。无论怎么传，那个被转义过的、PowerShell 不认识的路径字符串始终是"病灶"。

第三次尝试：对症下药，解决编码问题

既然知道了病因是 Git 的 quotepath 和 PowerShell 的编码识别问题，我们就可以对症下药了。

1. 强制 Git 输出原始路径：我们可以通过 git -c core.quotepath=false ... 临时禁用路径转义功能。
2. 确保 PowerShell 正确解码：通过 [System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8 命令，我们告诉 PowerShell 终端，请使用 UTF-8 编码来理解后续命令的输出。

结合这两点，我们得到了一个看起来非常有希望的命令：

# 方案三：解决编码问题，但引入新问题
[System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$fileList = (git -c core.quotepath=false ls-files) + (git -c core.quotepath=false ls-files --others --exclude-standard)
Compress-Archive -Path $fileList -DestinationPath "archive.zip" -Force

执行！成功了！没有报错！

然而，当我们兴冲冲地打开 archive.zip 时，心凉了半截——所有的文件都被拍平了，挤在压缩包的根目录，原有的项目目录结构荡然无存！

最后一次踩坑：Compress-Archive 的工作模式

这又是为什么？Compress-Archive 命令在接收到一大串独立的文件路径列表时，它的逻辑是：找到每一个文件，然后把它们一个个地、作为独立的个体放入压缩包的根目录。它并不会去分析这些文件原本的父目录是什么。

最终方案：返璞归真，先造结构再压缩

要保留目录结构，最可靠的方法就是告诉 Compress-Archive：“嘿，别管那些零散的文件了，请把这整个文件夹给我压起来。”

所以，我们的最终策略是：

1. 在一个安全的临时目录里，完整地重建项目的文件目录结构。
2. 然后对这个临时目录本身进行压缩。
3. 最后清理战场，删除临时目录。

这催生了我们最终的、完美的、健壮的 PowerShell 脚本：

# 终极解决方案：一个完整的自动化脚本

# 1. 确保 PowerShell 控制台能正确处理中文字符
[System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# 2. 定义临时目录名和最终的压缩文件名
$tempDir = ".\_archive_temp_$(Get-Date -Format "yyyyMMddHHmmss")"
$destinationZip = Join-Path $PWD "UrbanAirFM-archive.zip"

# 3. 获取所有需要打包的文件列表（禁用 git 的路径转义）
Write-Host "步骤 1/4: 正在获取文件列表..." -ForegroundColor Green
$fileList = (git -c core.quotepath=false ls-files) + (git -c core.quotepath=false ls-files --others --exclude-standard)

# 4. 创建临时目录，并按原有的目录结构将所有文件复制过去
Write-Host "步骤 2/4: 正在复制文件到临时目录以保持结构... (这可能需要一点时间)" -ForegroundColor Green
foreach ($file in $fileList) {
    # 构建在临时目录中的完整目标路径
    $destinationFile = Join-Path $tempDir $file
    # 获取目标文件的父目录
    $destinationParentDir = Split-Path -Path $destinationFile -Parent
    # 如果目标目录不存在，则创建它
    if (-not (Test-Path $destinationParentDir)) {
        New-Item -ItemType Directory -Path $destinationParentDir | Out-Null
    }
    # 复制文件
    Copy-Item -Path $file -Destination $destinationFile
}

# 5. 进入临时目录，将其中所有内容打包，这样可以保证压缩包内是正确的相对路径
Write-Host "步骤 3/4: 正在创建压缩包..." -ForegroundColor Green
Push-Location $tempDir
Compress-Archive -Path * -DestinationPath $destinationZip -Force
Pop-Location

# 6. 清理（删除）临时目录
Write-Host "步骤 4/4: 正在清理临时文件..." -ForegroundColor Green
Remove-Item -Path $tempDir -Recurse -Force

Write-Host "完成！压缩包已成功创建在您的项目根目录下。" -ForegroundColor Cyan

将这段脚本完整地复制到项目根目录的 PowerShell 终端中执行，一气呵成。最终得到的 UrbanAirFM-archive.zip 文件，不仅正确处理了所有中文文件名，还完美地保留了项目的原始目录结构。

总结与反思

这次看似简单的打包任务，实则是一次宝贵的实践。我们学到了：

1. 警惕工具间的"方言"：Git 的 core.quotepath 是一个需要注意的跨平台兼容性选项，在 Windows 脚本中与 git 交互时尤其要小心。
2. 明确指定编码：在处理包含非 ASCII 字符的场景下，显式设置控制台编码 ([System.Console]::OutputEncoding) 是一个好习惯。
3. 理解命令的本质：深入理解 Compress-Archive 的工作机制（处理文件列表 vs 处理单个目录）是解决目录结构问题的关键。
4. 复杂任务，脚本化思维：对于包含多个步骤、依赖和清理工作的任务，编写一个完整的脚本远比尝试拼接一条"惊为天人"的单行命令要来得更可靠、更易于维护。

希望这次踩坑之旅的记录，能为遇到类似问题的你，提供一条清晰的解决路径。