PowerShell脚本的版本控制与管理方法探讨

版本控制不是大公司的专属能力，对于日常编写PowerShell脚本的开发者来说，一套合理的版本管理方法能帮你避免大量的重复劳动和不可预测的故障。下面从基础概念开始，一步步讲清楚如何把PowerShell脚本纳入规范的版本管理流程。

一、为什么PowerShell脚本需要版本控制

1.1 脚本丢失或覆盖的噩梦

写脚本的人几乎都遇到过这种情况：辛辛苦苦写了半天，结果手滑把重要的旧版本覆盖了，或者误删了整个目录，备份也没有。这时候如果能用版本控制随时恢复任何一个历史版本，问题就迎刃而解了。

1.2 多人协作时的混乱场景

一个团队里，张三改了部署脚本的某个参数，李四改了日志输出的格式，两个人互不知情。最后线上部署出问题，谁也说不清是哪次修改引入的bug。版本控制能清晰记录每一次变更是谁做的、改了什么、什么时候改的。

1.3 变更可追溯，问题定位快

线上出了异常，需要快速定位是哪一次脚本修改导致的。如果有版本记录，对比出问题前后的代码差异，几分钟就能锁定问题所在，而不是靠记忆去猜。

二、选择合适的版本控制系统

2.1 Git：行业标准的分布式版本控制

Git是目前最主流的版本控制工具，它的分支模型让你可以在不影响主线代码的情况下尝试新的修改，合并时如果发现冲突也能精准定位问题。对于PowerShell脚本管理来说，Git的轻量级特性和跨平台能力尤其适合脚本类项目。

2.2 本地仓库与远程仓库的配合

Git的核心概念是"本地仓库"和"远程仓库"。本地仓库就是你电脑上的项目目录，远程仓库可以是GitHub、GitLab、Bitbucket等平台上的仓库。你的工作流通常是：本地修改 → 提交到本地仓库 → 推送到远程仓库 → 其他人拉取。

2.3 初始化一个PowerShell脚本仓库

下面的示例展示了如何从零开始初始化一个PowerShell脚本的Git仓库：

# ============================================
# 技术栈：PowerShell
# 用途：初始化一个PowerShell脚本项目的Git仓库
# ============================================

# 步骤1：创建项目目录
New-Item -ItemType Directory -Path "D:\Scripts\ServerDeploy" -Force
Set-Location "D:\Scripts\ServerDeploy"

# 步骤2：初始化Git仓库
git init

# 步骤3：创建基础脚本文件
@"
# ServerDeploy.ps1
# 用途：服务器自动部署脚本
# 作者：运维团队
# 版本：1.0.0

param(
    [string]$ServerName = "",
    [string]$PackagePath = "C:\Deploy\Packages"
)

Write-Host "=== 开始部署到服务器: $ServerName ===" -ForegroundColor Cyan

# 检查参数是否传入
if ([string]::IsNullOrWhiteSpace($ServerName)) {
    Write-Host "错误：未指定服务器名称" -ForegroundColor Red
    exit 1
}

# 检查安装包目录是否存在
if (-not (Test-Path $PackagePath)) {
    Write-Host "错误：安装包路径不存在 - $PackagePath" -ForegroundColor Red
    exit 1
}

# 执行部署操作
Write-Host "部署包路径: $PackagePath"
Write-Host "目标服务器: $ServerName"
Write-Host "=== 部署完成 ===" -ForegroundColor Green
"@ | Set-Content -Path "ServerDeploy.ps1" -Encoding UTF8

# 步骤4：创建.gitignore文件
@"
# 忽略临时文件和缓存
*.tmp
*.log
*.cache
.ps1_history

# 忽略IDE配置文件
.vscode/
.idea/

# 忽略环境变量文件
.env
config/settings.ps1
"@ | Set-Content -Path ".gitignore" -Encoding UTF8

# 步骤5：查看状态并提交
git status
git add .
git commit -m "初始提交：创建ServerDeploy脚本项目基础结构"

# 步骤6：推送到远程仓库（假设已创建远程仓库）
git remote add origin https://github.com/yourname/server-deploy.git
git branch -M main
git push -u origin main

# 输出结果
Write-Host "仓库初始化完成！当前状态如下：" -ForegroundColor Yellow
git log --oneline

三、PowerShell脚本的目录结构设计

3.1 模块化目录结构

一个好的目录结构能让脚本的可维护性大幅提升。不建议把所有逻辑堆在一个文件里，而是按照功能拆分成多个文件。

# ============================================
# 技术栈：PowerShell
# 用途：创建规范化的PowerShell脚本目录结构
# ============================================

# 创建目录结构
New-Item -ItemType Directory -Path "D:\Scripts\ServerDeploy" -Force
Set-Location "D:\Scripts\ServerDeploy"

# 主入口目录 - 存放脚本的入口文件
New-Item -ItemType Directory -Path ".\src" -Force

# 模块目录 - 存放可复用的函数和类
New-Item -ItemType Directory -Path ".\modules" -Force

# 配置目录 - 存放环境配置文件
New-Item -ItemType Directory -Path ".\config" -Force

# 测试目录 - 存放测试脚本
New-Item -ItemType Directory -Path ".\tests" -Force

# 文档目录 - 存放使用文档
New-Item -ItemType Directory -Path ".\docs" -Force

# 输出目录 - 存放运行日志和临时文件
New-Item -ItemType Directory -Path ".\output" -Force

Write-Host "目录结构创建完成：" -ForegroundColor Green
Get-ChildItem -Recurse -Directory | ForEach-Object { $_.FullName }

3.2 配置文件与代码分离

把配置文件和脚本逻辑分开，是版本管理中非常实用的做法。比如数据库连接字符串、API密钥这类信息，不应该硬编码在脚本里，而是放到单独的配置文件中，通过.gitignore排除敏感信息。

# ============================================
# 技术栈：PowerShell
# 用途：配置文件与脚本分离的最佳实践
# ============================================

# 创建配置文件模板（可提交到版本控制）
@"
# config/settings.template.ps1
# 配置文件模板 - 复制为settings.ps1后修改实际值
# 注意：settings.ps1已加入.gitignore，不会提交到仓库

$Config = @{
    # 数据库连接信息
    Database = @{
        Server = "localhost"
        Port = 1433
        Name = "MyDatabase"
    }
    
    # API配置
    Api = @{
        BaseUrl = "https://api.example.com"
        Timeout = 30
    }
    
    # 日志配置
    Logging = @{
        Level = "Info"
        OutputPath = "D:\Scripts\ServerDeploy\output\logs"
    }
}
"@ | Set-Content -Path "D:\Scripts\ServerDeploy\config\settings.template.ps1" -Encoding UTF8

# 创建实际配置文件（加入.gitignore，不提交）
@"
# config/settings.ps1
# 实际配置文件 - 请勿提交到版本控制
$Config = @{
    Database = @{
        Server = "prod-db-server"
        Port = 1433
        Name = "ProductionDB"
    }
    Api = @{
        BaseUrl = "https://api.example.com/v2"
        Timeout = 60
    }
    Logging = @{
        Level = "Debug"
        OutputPath = "D:\Scripts\ServerDeploy\output\logs\prod"
    }
}
"@ | Set-Content -Path "D:\Scripts\ServerDeploy\config\settings.ps1" -Encoding UTF8

# 创建主入口脚本，加载配置
@"
# src/Main.ps1
# 主入口脚本 - 加载配置并执行业务逻辑

# 加载配置文件
$ConfigPath = Join-Path $PSScriptRoot "..\config\settings.ps1"
if (Test-Path $ConfigPath) {
    . $ConfigPath
    Write-Host "配置文件加载成功: $ConfigPath" -ForegroundColor Green
} else {
    Write-Host "警告：未找到配置文件，使用默认配置" -ForegroundColor Yellow
    $Config = @{
        Database = @{ Server = "localhost"; Port = 1433; Name = "DefaultDB" }
    }
}

# 执行业务逻辑
Write-Host "正在连接到数据库 $($Config.Database.Server):$($Config.Database.Port)..."
# 这里写具体的业务逻辑
"@ | Set-Content -Path "D:\Scripts\ServerDeploy\src\Main.ps1" -Encoding UTF8

Write-Host "配置分离示例创建完成" -ForegroundColor Cyan

四、使用Git管理PowerShell脚本的日常工作流

4.1 日常提交规范

每次修改脚本后，遵循"提交信息写清楚"的原则。好的提交信息格式通常是"类型: 描述"，比如"修复: 修正数据库连接超时问题"或者"新增: 添加日志轮转功能"。

# ============================================
# 技术栈：PowerShell
# 用途：演示Git日常提交工作流
# ============================================

Set-Location "D:\Scripts\ServerDeploy"

# 场景1：修改脚本并查看差异
Write-Host "===== 场景1：查看脚本修改差异 =====" -ForegroundColor Yellow

# 先查看当前修改了哪些文件
git status

# 查看具体修改内容
git diff src/Main.ps1

# 提交修改（使用规范的提交信息）
git add src/Main.ps1
git commit -m "修复: 增加数据库连接超时重试机制"

Write-Host "===== 场景2：查看提交历史 =====" -ForegroundColor Yellow

# 查看最近5条提交记录
git log --oneline -5

# 查看详细的提交记录（包含修改内容概要）
git log --stat -3

Write-Host "===== 场景3：回滚到指定版本 =====" -ForegroundColor Yellow

# 回滚最近一次提交（保留修改内容，取消暂存）
git reset --soft HEAD~1

# 完全撤销最近一次提交（丢弃修改内容，慎用）
# git reset --hard HEAD~1

# 查看回滚后的状态
git log --oneline -5

Write-Host "===== 场景4：创建标签标记重要版本 =====" -ForegroundColor Yellow

# 创建标签，标记当前版本为v1.1.0
git tag -a v1.1.0 -m "v1.1.0: 添加数据库重试机制，修复连接超时问题"

# 查看所有标签
git tag -l

# 推送标签到远程仓库
git push origin v1.1.0

4.2 分支管理与协作策略

分支是Git最强大的功能之一。在PowerShell脚本开发中，建议采用"主分支+功能分支"的模式。main分支始终保持可部署状态，所有新功能开发都在独立的分支上进行，完成后再合并回主分支。

# ============================================
# 技术栈：PowerShell
# 用途：演示Git分支管理流程
# ============================================

Set-Location "D:\Scripts\ServerDeploy"

Write-Host "===== 1. 创建功能分支 =====" -ForegroundColor Cyan

# 确保主分支是最新的
git checkout main
git pull origin main

# 创建并切换到新功能分支
git checkout -b feature/add-healthcheck

# 在功能分支上编写新的健康检查功能
@"
# src/HealthCheck.ps1
# 用途：服务器健康检查脚本
# 功能：检查服务器各项服务是否正常运行

function Test-ServerHealth {
    param(
        [string]$ServerName,
        [array]$CheckItems = @("cpu", "memory", "disk")
    )
    
    $Results = @{ Status = "Healthy"; Details = @{} }
    
    # 检查CPU使用率
    if ($CheckItems -contains "cpu") {
        $CpuUsage = (Get-CimInstance Win32_Processor | Measure-Object -Property LoadPercentage -Average).Average
        $Results.Details["CPU"] = "$($CpuUsage)%"
        if ($CpuUsage -gt 90) {
            $Results.Status = "Warning"
        }
    }
    
    # 检查内存使用率
    if ($CheckItems -contains "memory") {
        $Memory = Get-CimInstance Win32_OperatingSystem
        $UsedMemory = [math]::Round(($Memory.TotalVisibleMemorySize - $Memory.FreePhysicalMemory) / 1MB, 2)
        $TotalMemory = [math]::Round($Memory.TotalVisibleMemorySize / 1MB, 2)
        $MemPercent = [math]::Round(($UsedMemory / $TotalMemory) * 100, 2)
        $Results.Details["Memory"] = "${MemPercent}% ($UsedMemory / $TotalMemory MB)"
    }
    
    return $Results
}

# 执行健康检查
$Result = Test-ServerHealth -ServerName "WebServer01" -CheckItems @("cpu", "memory")
if ($Result.Status -eq 'Healthy') { $Color = 'Green' } else { $Color = 'Red' }
Write-Host "服务器 $($Result.Status) 状态检查结果:" -ForegroundColor $Color
$Result.Details.GetEnumerator() | ForEach-Object { Write-Host "  $($_.Key): $($_.Value)" }
"@ | Set-Content -Path "src/HealthCheck.ps1" -Encoding UTF8

# 提交到功能分支
git add src/HealthCheck.ps1
git commit -m "新增: 添加服务器健康检查功能模块"

Write-Host "===== 2. 查看分支列表 =====" -ForegroundColor Cyan

# 查看所有分支
git branch -a

Write-Host "===== 3. 合并分支到主分支 =====" -ForegroundColor Cyan

# 切换回主分支
git checkout main

# 合并功能分支（使用--no-ff保留合并记录）
git merge feature/add-healthcheck --no-ff -m "合并: feature/add-healthcheck 分支，添加健康检查功能"

# 合并后删除已合并的功能分支
git branch -d feature/add-healthcheck

Write-Host "===== 4. 处理合并冲突（模拟） =====" -ForegroundColor Cyan

# 模拟冲突解决流程说明
Write-Host "如果合并时出现冲突，Git会标记冲突文件。"
Write-Host "使用git diff查看冲突内容，手动解决后执行："
Write-Host "  git add <冲突文件>"
Write-Host "  git commit -m '解决合并冲突'"

Write-Host "分支管理演示完成" -ForegroundColor Green

4.3 合并请求（Pull Request）工作流

在团队协作场景中，合并请求是代码审查的核心环节。开发者在功能分支上完成开发后，发起合并请求，团队成员可以进行代码审查、提出修改建议，确认无误后再合并。

# ============================================
# 技术栈：PowerShell
# 用途：模拟合并请求（PR）审查流程
# ============================================

Set-Location "D:\Scripts\ServerDeploy"

Write-Host "===== 模拟合并请求审查流程 =====" -ForegroundColor Yellow

# 展示代码审查中发现的典型问题
@"
# 审查目标：src/DataProcess.ps1
# 审查者发现的问题及建议：

# 问题1：缺少错误处理
# 原代码：
#   $File = Get-Content "data.csv"
# 建议修改：
#   try {
#       $File = Get-Content -Path "data.csv" -ErrorAction Stop
#   } catch {
#       Write-Error "读取文件失败: $_"
#       exit 1
#   }

# 问题2：硬编码的路径
# 原代码：
#   $OutputPath = "C:\temp\result.txt"
# 建议修改：
#   $OutputPath = Join-Path $env:TEMP "result.txt"

# 问题3：未验证输入参数
# 原代码：
#   function Process-Data($Input) { ... }
# 建议修改：
#   function Process-Data {
#       param(
#           [Parameter(Mandatory)] [string]$Input
#       )
#       if ([string]::IsNullOrWhiteSpace($Input)) {
#           throw "输入不能为空"
#       }
#   }
"@ | Set-Content -Path "docs/CodeReviewExample.txt" -Encoding UTF8

# 在本地查看提交日志，模拟审查
Write-Host "`n查看待审查的提交：" -ForegroundColor Cyan
git log --oneline -10

Write-Host "`n审查要点清单：" -ForegroundColor Cyan
$ReviewChecklist = @(
    "[ ] 是否有适当的错误处理（try-catch）",
    "[ ] 是否避免了硬编码路径和参数",
    "[ ] 是否有输入参数验证",
    "[ ] 注释是否清晰准确",
    "[ ] 是否遵循命名规范",
    "[ ] 是否考虑了性能影响",
    "[ ] 敏感信息是否已从代码中移除"
)
$ReviewChecklist | ForEach-Object { Write-Host "  $_" }

Write-Host "`n审查完成后，在PR页面填写审查意见并提交。" -ForegroundColor Green

五、脚本的模块化与依赖管理

5.1 PowerShell模块的创建与引用

随着脚本功能越来越复杂，把所有代码写在一个文件里会变得越来越难以维护。PowerShell提供了模块机制，可以把相关的函数打包成一个模块，在需要时按需加载。

# ============================================
# 技术栈：PowerShell
# 用途：创建和使用PowerShell模块
# ============================================

# 创建模块目录结构
$ModulePath = "D:\Scripts\MyModules\DeployHelper"
New-Item -ItemType Directory -Path $ModulePath -Force

# 创建模块文件（存放函数实现）
@"
# DeployHelper.psm1
# 用途：部署辅助函数模块
# 版本：2.0.0

# 导出给外部使用的函数
function New-DeployPackage {
    <#
    .SYNOPSIS
        创建部署包

    .DESCRIPTION
        将指定目录打包为zip文件，用于服务器部署

    .PARAMETER SourcePath
        源文件目录路径

    .PARAMETER PackageName
        部署包名称

    .EXAMPLE
        New-DeployPackage -SourcePath "D:\Project" -PackageName "app-v1.0"
    #>
    param(
        [Parameter(Mandatory)] [string]$SourcePath,
        [Parameter(Mandatory)] [string]$PackageName
    )

    $OutputDir = Join-Path $env:TEMP "DeployPackages"
    if (-not (Test-Path $OutputDir)) {
        New-Item -ItemType Directory -Path $OutputDir -Force | Out-Null
    }

    $ZipPath = Join-Path $OutputDir "$PackageName.zip"
    if (Test-Path $ZipPath) {
        Remove-Item $ZipPath -Force
    }

    try {
        Compress-Archive -Path "$SourcePath\*" -DestinationPath $ZipPath
        Write-Host "部署包创建成功: $ZipPath" -ForegroundColor Green
        return $ZipPath
    } catch {
        Write-Error "创建部署包失败: $_"
        return $null
    }
}

function Invoke-RemoteDeploy {
    <#
    .SYNOPSIS
        远程部署到目标服务器

    .DESCRIPTION
        通过WinRM将部署包发送到远程服务器并执行部署

    .PARAMETER ServerName
        目标服务器名称

    .PARAMETER PackagePath
        本地部署包路径

    .EXAMPLE
        Invoke-RemoteDeploy -ServerName "Web01" -PackagePath "C:\temp\app-v1.0.zip"
    #>
    param(
        [Parameter(Mandatory)] [string]$ServerName,
        [Parameter(Mandatory)] [string]$PackagePath
    )

    if (-not (Test-Path $PackagePath)) {
        Write-Error "部署包不存在: $PackagePath"
        return
    }

    try {
        Write-Host "正在连接到 $ServerName ..." -ForegroundColor Cyan

        Invoke-Command -ComputerName $ServerName -ScriptBlock {
            param($pkgPath)
            Write-Host "在远程服务器上执行部署: $pkgPath"
        } -ArgumentList $PackagePath

        Write-Host "远程部署命令发送成功" -ForegroundColor Green
    } catch {
        Write-Error "远程部署失败: $_"
    }
}
"@ | Set-Content -Path "$ModulePath\DeployHelper.psm1" -Encoding UTF8

# 创建模块清单文件
@"
@{
    RootModule        = 'DeployHelper.psm1'
    ModuleVersion     = '2.0.0'
    Author            = '运维团队'
    Description       = '部署辅助函数模块，提供部署包创建和远程部署功能'
    FunctionsToExport = @('New-DeployPackage', 'Invoke-RemoteDeploy')
}
"@ | Set-Content -Path "$ModulePath\DeployHelper.psd1" -Encoding UTF8

# 导入模块并使用
Import-Module -Name $ModulePath -Force

Write-Host "模块导入成功，可用函数：" -ForegroundColor Cyan
Get-Command -Module DeployHelper | Select-Object Name, CommandType | Format-Table

5.2 依赖关系管理

当你的PowerShell脚本依赖某些第三方模块时，需要管理这些依赖。可以使用PowerShell Gallery来安装和引用外部模块。

# ============================================
# 技术栈：PowerShell
# 用途：管理PowerShell脚本的外部依赖
# ============================================

# 检查是否已安装PowerShellGet
if (-not (Get-Module -ListAvailable -Name PowerShellGet)) {
    Write-Host "正在安装PowerShellGet..." -ForegroundColor Yellow
    Install-Module -Name PowerShellGet -Force
}

# 安装PSScriptAnalyzer（代码质量检查工具）
Write-Host "检查并安装PSScriptAnalyzer..." -ForegroundColor Cyan
if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
    Install-Module -Name PSScriptAnalyzer -Force
} else {
    Write-Host "PSScriptAnalyzer 已安装" -ForegroundColor Green
}

# 查看当前已安装的所有相关模块
Write-Host "`n已安装的相关模块列表：" -ForegroundColor Yellow
Get-Module -ListAvailable | Where-Object { $_.Name -like "PS*" -or $_.Name -like "*Deploy*" } | 
    Select-Object Name, Version, Path | Format-Table -AutoSize

# 创建依赖清单文件，方便新成员快速安装所有依赖
@"
# requirements.txt
# 项目依赖清单 - 记录项目所需的所有PowerShell模块及版本
# 使用方法：逐行安装，如 Install-Module -Name PSScriptAnalyzer -RequiredVersion 1.21.0

PSScriptAnalyzer = 1.21.0
PSReadLine = 2.3.4
ImportExcel = 7.8.0
PoshGit = 0.7.0
Pester = 5.5.0
"@ | Set-Content -Path "D:\Scripts\ServerDeploy\requirements.txt" -Encoding UTF8

Write-Host "依赖管理示例完成" -ForegroundColor Green

六、自动化测试与持续集成

6.1 为PowerShell脚本编写单元测试

写完脚本不测试就提交，是版本管理中最大的隐患之一。Pester是编写PowerShell单元测试的标准工具，通过编写自动化测试用例，可以在每次修改后快速验证功能是否正常运行。

# ============================================
# 技术栈：PowerShell
# 用途：使用Pester为PowerShell脚本编写单元测试
# ============================================

# 确保Pester已安装
if (-not (Get-Module -ListAvailable -Name Pester)) {
    Install-Module -Name Pester -Force
}
Import-Module Pester -MinimumVersion 5.0

# 创建被测函数
@"
function Convert-FileSize {
    param(
        [Parameter(Mandatory)] [double]$Bytes
    )
    
    if ($Bytes -lt 0) {
        throw "字节数不能为负数"
    }
    
    $Units = @("B", "KB", "MB", "GB", "TB")
    $UnitIndex = 0
    
    while ($Bytes -ge 1024 -and $UnitIndex -lt ($Units.Length - 1)) {
        $Bytes = $Bytes / 1024
        $UnitIndex++
    }
    
    return "$([math]::Round($Bytes, 2)) $($Units[$UnitIndex])"
}
"@ | Set-Content -Path "D:\Scripts\ServerDeploy\src\ConvertFunctions.ps1" -Encoding UTF8

# 编写Pester测试文件
@"
# tests/ConvertFunctions.Tests.ps1
# 用途：Convert-FileSize 函数的单元测试

Describe 'Convert-FileSize 函数' {
    
    # 测试基本功能
    It '应该将0字节转换为0 B' {
        Convert-FileSize -Bytes 0 | Should -Be '0 B'
    }
    
    It '应该将1024字节转换为1 KB' {
        Convert-FileSize -Bytes 1024 | Should -Be '1 KB'
    }
    
    It '应该将1048576字节转换为1 MB' {
        Convert-FileSize -Bytes 1048576 | Should -Be '1 MB'
    }
    
    # 测试边界条件
    It '应该处理小数结果' {
        Convert-FileSize -Bytes 1536 | Should -Be '1.5 KB'
    }
    
    It '应该处理非常大的数值' {
        Convert-FileSize -Bytes 1099511627776 | Should -Be '1 TB'
    }
    
    # 测试异常场景
    It '应该抛出异常当输入为负数' {
        { Convert-FileSize -Bytes -100 } | Should -Throw '字节数不能为负数'
    }
    
    It '应该抛出异常当未提供参数' {
        { Convert-FileSize } | Should -Throw
    }
    
}
"@ | Set-Content -Path "D:\Scripts\ServerDeploy\tests\ConvertFunctions.Tests.ps1" -Encoding UTF8

Write-Host "测试文件创建完成，请执行以下命令运行测试：" -ForegroundColor Yellow
Write-Host "  Invoke-Pester -Path '.\tests\ConvertFunctions.Tests.ps1' -Output Detailed"

6.2 使用PowerShell进行CI/CD集成

持续集成和持续部署是将版本控制与自动化部署结合的关键。通过在每次代码提交时自动运行测试和部署流程，可以大幅降低线上故障的概率。

# ============================================
# 技术栈：PowerShell
# 用途：CI/CD流水线脚本示例
# ============================================

# CI脚本 - 每次推送时自动执行
@"
# scripts/CIBuild.ps1
# 用途：CI构建流水线脚本
# 触发条件：代码推送、合并请求

param(
    [string]$Branch = "main",
    [string]$BuildNumber = "",
    [string]$GitCommit = ""
)

Write-Host "===== CI 构建开始 =====" -ForegroundColor Cyan
Write-Host "分支: $Branch"
Write-Host "构建编号: $BuildNumber"
Write-Host "Git提交: $GitCommit"

# 步骤1：代码质量检查
Write-Host "`n--- 步骤1: 代码质量检查 ---" -ForegroundColor Yellow
$PSScriptAnalyzer = Get-Module -ListAvailable PSScriptAnalyzer
if ($PSScriptAnalyzer) {
    $AnalysisResult = Invoke-ScriptAnalyzer -Path ".\src\*.ps1" -Recurse
    if ($AnalysisResult) {
        Write-Host "发现 $($AnalysisResult.Count) 个代码质量问题：" -ForegroundColor Red
        $AnalysisResult | Format-Table -AutoSize
    } else {
        Write-Host "代码质量检查通过，无问题发现" -ForegroundColor Green
    }
}

# 步骤2：运行单元测试
Write-Host "`n--- 步骤2: 运行单元测试 ---" -ForegroundColor Yellow
$TestResult = Invoke-Pester -Path ".\tests\*.Tests.ps1" -PassThru
if ($TestResult.FailedCount -gt 0) {
    Write-Host "测试失败: $($TestResult.FailedCount) 个用例未通过" -ForegroundColor Red
    exit 1
} else {
    Write-Host "所有测试通过: $($TestResult.TotalCount) 个用例" -ForegroundColor Green
}

# 步骤3：打包构建产物
Write-Host "`n--- 步骤3: 打包构建产物 ---" -ForegroundColor Yellow
$PackagePath = New-DeployPackage -SourcePath ".\src" -PackageName "build-$BuildNumber"
if ($PackagePath -eq $null) {
    Write-Host "打包失败" -ForegroundColor Red
    exit 1
}

Write-Host "`n===== CI 构建完成 =====" -ForegroundColor Green
"@ | Set-Content -Path "D:\Scripts\ServerDeploy\scripts\CIBuild.ps1" -Encoding UTF8

# CD脚本 - 部署到目标环境
@"
# scripts/CIDeploy.ps1
# 用途：CD部署流水线脚本
# 触发条件：CI构建成功

param(
    [string]$TargetEnvironment = "staging",
    [string]$PackagePath = "",
    [string]$ServerName = ""
)

Write-Host "===== CD 部署开始 =====" -ForegroundColor Cyan
Write-Host "目标环境: $TargetEnvironment"
Write-Host "部署包: $PackagePath"
Write-Host "目标服务器: $ServerName"

# 预部署检查
Write-Host "`n--- 预部署检查 ---" -ForegroundColor Yellow

# 检查部署包是否存在
if (-not (Test-Path $PackagePath)) {
    Write-Host "错误：部署包不存在" -ForegroundColor Red
    exit 1
}

# 检查目标服务器连通性
$ServerStatus = Test-Connection -ComputerName $ServerName -Count 1 -Quiet
if (-not $ServerStatus) {
    Write-Host "错误：无法连接到目标服务器" -ForegroundColor Red
    exit 1
}

# 执行部署
Write-Host "`n--- 执行部署 ---" -ForegroundColor Yellow
Write-Host "开始部署到 $ServerName..."
# 这里调用实际的部署函数
# Invoke-RemoteDeploy -ServerName $ServerName -PackagePath $PackagePath

# 部署后验证
Write-Host "`n--- 部署后验证 ---" -ForegroundColor Yellow
# 验证服务是否正常运行

Write-Host "`n===== CD 部署完成 =====" -ForegroundColor Green
"@ | Set-Content -Path "D:\Scripts\ServerDeploy\scripts\CIDeploy.ps1" -Encoding UTF8

Write-Host "CI/CD脚本创建完成" -ForegroundColor Green

七、应用场景分析

7.1 运维自动化脚本管理

在运维场景中，自动化脚本通常涉及服务器部署、配置管理、备份恢复等关键操作。这些脚本一旦出问题，直接影响线上服务稳定性。通过版本控制，可以确保每次部署都有明确的变更记录，出现问题时能快速回滚到上一个稳定版本。比如一个数据库备份脚本，每次修改备份策略时都有记录，出了问题可以立刻回滚到上一个正常的备份策略。

7.2 开发环境配置脚本管理

开发团队通常需要一套环境配置脚本，用于新成员入职时的环境搭建。这些脚本涉及IDE配置、开发工具安装、环境变量设置等内容。使用版本控制可以确保所有团队成员使用一致的、经过验证的环境配置，避免"在我电脑上能跑"的经典问题。

7.3 数据分析与处理脚本管理

在数据分析领域，PowerShell脚本经常用于批量数据处理、日志分析、报表生成等任务。这些脚本通常需要反复调优，版本控制能帮助数据分析师追踪每一次修改的效果，快速对比不同版本的输出结果，确保数据分析的准确性和可重复性。

7.4 安全审计与合规检查

安全团队使用PowerShell脚本进行合规检查、漏洞扫描、权限审计等工作。这些脚本的执行结果往往需要存档以备审计。版本控制天然提供了脚本的完整历史，方便追溯每一版本的检查逻辑，确保审计过程的可追溯性。

八、技术优缺点分析

8.1 优势

版本控制为PowerShell脚本管理带来了多方面的价值。首先是可追溯性，每一次代码修改都有明确的记录，谁在什么时候改了什么，一目了然。其次是协作效率，多人可以同时在不同分支上开发，互不干扰，通过合并请求实现代码审查和质量把控。再次是回滚能力，当新版本出现问题时，可以快速回滚到之前的稳定版本，减少故障恢复时间。

对于PowerShell这种脚本语言来说，版本控制还有一个特殊的价值——安全性。由于脚本经常涉及系统级操作，未经审查的代码变更可能导致意外后果。通过分支保护和合并请求机制，可以确保所有代码变更都经过审查，降低误操作的风险。

8.2 局限性

不过，版本控制也有其局限性。首先是学习成本，对于不熟悉的开发者来说，Git的分支模型和命令体系需要一定的学习曲线。其次是仓库大小，随着提交历史的积累，仓库体积会逐渐增大，尤其是当频繁修改大文件时。

另一个需要注意的是，版本控制只管代码变更，不管脚本的运行时行为。脚本依赖的外部服务、环境变量、系统权限等因素不在版本控制范围内，需要额外的管理手段来确保运行环境的一致性。

8.3 与同类工具的对比

与直接编辑保存相比，版本控制的优势非常明显。直接编辑无法追踪变更历史，无法多人协作，无法回滚。与简单的文件备份相比，版本控制更精确，可以追踪每一行的修改，更高效，不需要手动备份，更安全，有审查机制作为保障。

九、注意事项

9.1 敏感信息处理

将敏感信息（如密码、API密钥、数据库连接字符串）提交到版本控制仓库是严重的违规行为。必须将这些信息放到.gitignore排除的文件中，或者使用环境变量、密钥管理服务等方式来管理。如果不小心提交了敏感信息，需要立即清理历史。

# ============================================
# 技术栈：PowerShell
# 用途：敏感信息处理最佳实践
# ============================================

# 使用环境变量存储敏感信息
@"
# 推荐做法：敏感信息通过环境变量传递
# 在脚本中这样引用：
#   $DbPassword = $env:DB_PASSWORD
#   $ApiKey = $env:API_KEY

# 在Windows中设置持久环境变量（需要管理员权限）：
# [Environment]::SetEnvironmentVariable('DB_PASSWORD', 'your_password', 'Machine')

# 在PowerShell中设置会话级环境变量：
# $env:DB_PASSWORD = 'your_password'
"@ | Set-Content -Path "docs/SensitiveInfoGuide.md" -Encoding UTF8

# 示例：安全的脚本编写方式
@"
# src/SecureScript.ps1
# 安全示例：从环境变量读取敏感配置

param()

# 从环境变量读取配置，而不是硬编码
$DbHost = $env:DB_HOST
$DbPort = $env:DB_PORT
$DbName = $env:DB_NAME
$DbUser = $env:DB_USER
$DbPass = $env:DB_PASSWORD

# 验证必需的环境变量是否已设置
$RequiredVars = @(
    @{ Name = "DB_HOST"; Value = $DbHost },
    @{ Name = "DB_PORT"; Value = $DbPort },
    @{ Name = "DB_NAME"; Value = $DbName },
    @{ Name = "DB_USER"; Value = $DbUser },
    @{ Name = "DB_PASSWORD"; Value = $DbPass }
)

foreach ($Var in $RequiredVars) {
    if ([string]::IsNullOrWhiteSpace($Var.Value)) {
        Write-Error "缺少必要的环境变量: $($Var.Name)"
        exit 1
    }
}

Write-Host "所有环境变量已验证，可以安全执行脚本" -ForegroundColor Green
"@ | Set-Content -Path "D:\Scripts\ServerDeploy\src\SecureScript.ps1" -Encoding UTF8

9.2 提交信息的规范化

规范的提交信息有助于后续的变更追踪和版本管理。建议采用约定式提交规范，格式为类型: 描述，常见类型包括feat（新功能）、fix（修复）、docs（文档）、refactor（重构）、test（测试）等。

# ============================================
# 技术栈：PowerShell
# 用途：约定式提交示例
# ============================================

Write-Host "===== 约定式提交信息示例 =====" -ForegroundColor Cyan

$CommitExamples = @(
    "feat: 添加服务器健康检查功能",
    "fix: 修复数据库连接超时未重试的问题",
    "fix(deploy): 修正部署脚本中路径拼接错误",
    "docs: 更新部署说明文档",
    "refactor: 重构配置加载逻辑，提升可读性",
    "test: 为数据转换函数添加单元测试",
    "chore: 更新.gitignore规则",
    "perf: 优化大文件处理性能，减少内存占用",
    "ci: 配置GitHub Actions自动化构建",
    "style: 统一代码缩进和注释格式"
)

$CommitExamples | ForEach-Object { Write-Host "  $_" }

Write-Host "`n好的提交信息特点：" -ForegroundColor Green
Write-Host "  1. 使用简短动词开头"
Write-Host "  2. 不超过50个字符"
Write-Host "  3. 说明做了什么改动"
Write-Host "  4. 关联Issue时使用 #数字 格式"

9.3 分支保护规则

在团队协作中，建议对主分支设置保护规则，禁止直接推送到主分支，所有变更必须通过合并请求。这样可以确保所有代码都经过审查，降低引入bug的风险。

# ============================================
# 技术栈：PowerShell
# 用途：配置GitHub分支保护规则（通过API）
# ============================================

# 注意：实际使用中需要GitHub Personal Access Token
# 这里展示配置思路，实际执行需要替换为真实Token

@"
# 分支保护配置说明
# 配置步骤（手动操作）：
# 1. 进入GitHub仓库 → Settings → Branches → Add branch protection rule
# 2. 设置分支名称模式为 "main"
# 3. 勾选以下规则：
#    - Require pull request before merging（合并前需要PR）
#    - Require approvals（需要至少1-2个审批）
#    - Require status checks to pass（状态检查必须通过）
#    - Require linear history（保持线性历史）
#    - Restrict who can push to matching branches（限制谁可以推送）
#    - Include administrators（管理员也需要遵守）

# 安全提醒：
# - Token应存储在环境变量中，不要硬编码在脚本里
# - 定期轮换Token，降低泄露风险
# - 使用最小权限原则，只授予必要的API权限
"@ | Set-Content -Path "docs/BranchProtectionGuide.md" -Encoding UTF8

Write-Host "分支保护配置指南已保存到 docs/BranchProtectionGuide.md" -ForegroundColor Green

9.4 定期清理和归档

随着时间推移，Git仓库可能会积累大量过时的分支和标签。建议定期清理已合并的功能分支，归档不再维护的旧版本，保持仓库的整洁。

# ============================================
# 技术栈：PowerShell
# 用途：仓库清理与归档
# ============================================

Set-Location "D:\Scripts\ServerDeploy"

Write-Host "===== 仓库清理脚本 =====" -ForegroundColor Yellow

# 查看已合并到main的分支
Write-Host "`n已合并到main的分支：" -ForegroundColor Cyan
git branch --merged main

# 查看未合并的分支
Write-Host "`n未合并到main的分支：" -ForegroundColor Cyan
git branch --no-merged main

# 删除已合并的本地分支（除main外）
$MergedBranches = git branch --merged main | Select-String -Pattern '^\s' | ForEach-Object { $_.Trim() }
foreach ($Branch in $MergedBranches) {
    if ($Branch -ne "main") {
        Write-Host "删除已合并分支: $Branch"
        git branch -d $Branch
    }
}

# 查看标签
Write-Host "`n当前标签列表：" -ForegroundColor Cyan
git tag -l

# 清理过期的远程跟踪引用
Write-Host "`n清理远程跟踪引用..." -ForegroundColor Cyan
git fetch --prune
git remote prune origin

Write-Host "`n===== 仓库清理完成 =====" -ForegroundColor Green
git status

十、文章总结

PowerShell脚本的版本控制和管理，本质上是用规范化的流程来替代随意的文件管理习惯。通过Git进行版本追踪，通过模块化设计提升可维护性，通过测试和CI/CD保证质量，通过分支保护和合并请求实现团队协作——这些方法组合在一起，可以让脚本开发从"个人作坊"升级为"团队协作"模式。

对于初学者的建议是从最简单的版本控制开始：初始化一个Git仓库，每次修改后提交，保持提交信息清晰。随着经验积累，再逐步引入分支管理、代码审查、自动化测试等高级实践。不要一开始就追求完美的流程，先养成"写完就提交"的习惯，这是所有高级实践的基础。

版本控制的核心价值不是工具本身，而是它带来的变更可追溯、协作可管理、问题可定位这些能力。在运维和开发工作中，脚本往往承担着重大的职责，给它们加上版本控制这层保障，是对工作负责的表现，也是对团队负责的表现。