DoitCore

markdown

# PowerShell 多级目录结构递归替换工具指南

## 功能概述
本工具用于递归替换文件系统中任意位置的连续目录结构，支持以下核心功能：
- 动态层级替换（支持1-N层目录结构）
- 安全预览模式（-WhatIf参数）
- 智能路径验证
- 执行前二次确认
- 内容无损迁移
- 空目录自动清理

## 完整脚本代码

```powershell
param(
    [Parameter(Mandatory = $true)]
    [string]$OldStructure,
    
    [Parameter(Mandatory = $true)]
    [string]$NewStructure,
    
    [Parameter()]
    [ValidateScript({
        if (-not (Test-Path $_ -PathType Container)) {
            throw "路径不存在或不是目录: $_"
        }
        $true
    })]
    [string]$RootPath = $(Get-Location).Path,
    
    [switch]$WhatIf
)

$oldParts = $OldStructure -split '/'
$newParts = $NewStructure -split '/'
$structureDepth = $oldParts.Count

if ($oldParts.Count -ne $newParts.Count) {
    throw "错误：旧结构 ($structureDepth 层) 与新结构 ($($newParts.Count) 层) 的层级数量不一致"
}

$regexPattern = ($oldParts | ForEach-Object { [regex]::Escape($_) }) -join '\\'
$fullMatchPattern = "(.*?\\?)($regexPattern)(\\|$)"

Write-Host "正在扫描目录 (旧结构深度: $structureDepth 层)..." -ForegroundColor Cyan
Write-Host "扫描根目录: $RootPath" -ForegroundColor DarkGray

$candidates = Get-ChildItem -Path $RootPath -Recurse -Directory |
    Where-Object { $_.FullName -match $fullMatchPattern } |
    Sort-Object { $_.FullName.Split('\').Count } -Descending

if (-not $candidates) {
    Write-Host "未找到匹配的目录结构" -ForegroundColor Yellow
    exit
}

if (-not $WhatIf) {
    # 安全确认提示内容
    # ...
}

foreach ($dir in $candidates) {
    try {
        # 路径替换和操作逻辑
        # ...
    }
    catch {
        Write-Warning "操作失败: $($dir.FullName)"
        Write-Warning $_.Exception.Message
    }
}

if ($WhatIf) {
    Write-Host "`n预览模式已结束 (模拟影响目录数: $($candidates.Count))" -ForegroundColor Cyan
} else {
    Write-Host "`n成功完成结构替换 (实际处理目录数: $($candidates.Count))" -ForegroundColor Green
}

使用说明

基本参数

参数	说明	示例值
-OldStructure	要替换的旧结构（/分隔）	"old/project"
-NewStructure	新目录结构（/分隔）	"new/backup"
-RootPath	搜索根目录（默认当前目录）	"D:\data"
-WhatIf	启用预览模式	[开关参数]

使用示例

powershell

# 预览模式（单层结构）
.\rename.ps1 -OldStructure "temp" -NewStructure "cache" -WhatIf

# 实际执行（多层结构）
.\rename.ps1 -OldStructure "project/src" -NewStructure "archive/code" -RootPath "C:\work"

# 复杂结构替换（当前目录）
.\rename.ps1 -OldStructure "a/b/c/d" -NewStructure "x/y/z/w"

典型输出

正在扫描目录 (旧结构深度: 2 层)...
扫描根目录: C:\test

即将执行以下操作：
根目录    : C:\test
旧结构    : a/b (共 2 层)
新结构    : x/y (共 2 层)
影响目录数: 3
示例修改  :
  C:\test\demo\a\b
  → C:\test\demo\x\y

技术原理

正则表达式构建

powershell

# 示例：将 "a/b/c" 转换为正则模式
$regexPattern = "a\\b\\c"
$fullMatchPattern = "(.*?\\?)(a\\b\\c)(\\|$)"

匹配模式说明：

(.*?\\?) 捕获前置路径
(a\\b\\c) 精确匹配目标结构
(\\|$) 确保结构完整性

目录处理算法

深度优先扫描：Get-ChildItem -Recurse
结构匹配：正则表达式全文匹配
排序机制：按路径深度降序排列
原子操作：
- 新建目标目录
- 迁移文件内容
- 删除源目录

注意事项

安全规范

始终先在测试目录验证
生产环境操作前必须使用-WhatIf
确保对目标目录有完全控制权限
避免在系统目录（如Windows、Program Files）操作

异常处理

错误类型	处理方式
路径不存在	验证脚本自动拦截
权限不足	捕获异常并跳过
文件正在使用	记录错误继续后续操作
目录非空	保留源目录并显示警告

扩展知识

PowerShell特性应用

参数验证：

powershell

[ValidateScript({Test-Path $_})]  # 路径存在性检查

管道优化：

powershell

Get-ChildItem | Where-Object | Sort-Object  # 流式处理提升性能

路径操作：

powershell

$_.FullName.Split('\')  # 跨平台路径分割

正则表达式特殊处理

转义处理：

powershell

[regex]::Escape("test.dir") → "test\.dir"

上下文保留：

powershell

-replace "(prefix)$regexPattern", "`$1$newStructure"

版本更新日志

版本	主要特性
1.0	基础多级目录替换功能
1.1	增加-WhatIf参数和安全确认
1.2	支持动态层级结构
1.3	优化根目录默认值处理
1.4	增强正则匹配算法和错误处理机制

使用说明 ​

基本参数 ​

使用示例 ​

典型输出 ​

技术原理 ​

正则表达式构建 ​

目录处理算法 ​

注意事项 ​

安全规范 ​

异常处理 ​

扩展知识 ​

PowerShell特性应用 ​

正则表达式特殊处理 ​

版本更新日志 ​

推荐测试方案 ​

使用说明

基本参数

使用示例

典型输出

技术原理

正则表达式构建

目录处理算法

注意事项

安全规范

异常处理

扩展知识

PowerShell特性应用

正则表达式特殊处理

版本更新日志

推荐测试方案