用 winget + PowerShell 自動化 PC 配置 ── 讓操作手冊變得可執行

# 準確指定 ID 來安裝(-e 為完全比對,--id 指定 ID)
#   --silent                     : 不顯示 UI
#   --accept-package-agreements  : 同意套件的使用條款
#   --accept-source-agreements   : 同意來源的使用條款
#   --scope machine              : 為所有使用者安裝(僅限支援的套件)
# 換行用的反引號要放在行尾。若後面接註解就不算是換行
winget install --id Google.Chrome -e --silent `
    --accept-package-agreements --accept-source-agreements --scope machine

# 查詢 ID
winget search "Visual Studio Code"
winget show --id Microsoft.VisualStudioCode

# 確認是否有機器範圍(machine scope)的安裝程式
winget show --id Google.Chrome -e --scope machine

# 為了比較,也看一下使用者範圍(user scope)
winget show --id Google.Chrome -e --scope user

# 從標準 PC 把已導入套件的清單寫出為 JSON
winget export --output D:\kitting\apps.json --include-versions

# 在新的 PC 上還原
winget import --import-file D:\kitting\apps.json `
    --accept-package-agreements --accept-source-agreements --ignore-unavailable

# 套用前先確認內容(顯示將執行的操作)
winget configure show --file D:\kitting\kitting.winget

# 套用
winget configure --file D:\kitting\kitting.winget --accept-configuration-agreements

#Requires -RunAsAdministrator
[CmdletBinding()]
param(
    [string] $ConfigPath = "$PSScriptRoot\kitting.config.json"
)

$ErrorActionPreference = 'Stop'
# 5.1 的 Get-Content 若沒有 BOM,會以 ANSI 字碼頁讀取。
# 在日文環境中讀取 UTF-8 的 JSON 會亂碼,因此明確指定編碼
$config = Get-Content $ConfigPath -Raw -Encoding utf8 | ConvertFrom-Json
$rebootRequired  = $false
$rebootInitiated = $false
$log    = "C:\ProgramData\KsKitting\kitting_$(Get-Date -f yyyyMMdd_HHmmss).log"
$null   = New-Item -Path (Split-Path $log) -ItemType Directory -Force

# 後述的使用者單位階段是在另一個處理序中執行的,因此要把設定
# 分發到所有使用者都能讀取的位置。
# 若把發布物放在這個位置直接執行,複製來源與目的地會是同一個檔案。
# Copy-Item 把複製到自身視為錯誤,因此在 $ErrorActionPreference = 'Stop'
# 的設定下,腳本會在配置開始之前就整個停止
$sharedConfig = 'C:\ProgramData\KsKitting\kitting.config.json'
$sourceFull   = (Resolve-Path $ConfigPath).ProviderPath
$sharedFull   = if (Test-Path $sharedConfig) { (Resolve-Path $sharedConfig).ProviderPath } else { '' }
if (-not [string]::Equals($sourceFull, $sharedFull, 'OrdinalIgnoreCase')) {
    Copy-Item $ConfigPath $sharedConfig -Force
}
Start-Transcript -Path $log -Append

try {
    # --- 1. 標準資料夾 ------------------------------------------------
    foreach ($dir in $config.folders) {
        if (-not (Test-Path $dir)) {
            $null = New-Item -Path $dir -ItemType Directory
            Write-Verbose "建立: $dir"
        }
    }

    # --- 2. 公司內部標準的登錄設定 --------------------------------------
    foreach ($reg in $config.registry) {
        if (-not (Test-Path $reg.key)) { $null = New-Item -Path $reg.key -Force }
        $item   = Get-Item -Path $reg.key
        $exists = $item.GetValueNames() -contains $reg.name

        # 不只比較「值」,也要比較「型別」。REG_SZ 的 "1" 和 DWORD 的 1
        # 在 PowerShell 的比較中會被視為相等,導致把實際上並未生效的設定
        # 誤判為「已套用」
        $sameValue = $exists -and $item.GetValue($reg.name) -eq $reg.value
        $sameKind  = $exists -and $item.GetValueKind($reg.name).ToString() -eq $reg.type

        if (-not ($sameValue -and $sameKind)) {
            Set-ItemProperty -Path $reg.key -Name $reg.name -Value $reg.value -Type $reg.type
            Write-Verbose "設定: $($reg.key)\$($reg.name) = $($reg.value) ($($reg.type))"
        }
    }

    # --- 3. Windows 功能 --------------------------------------------------
    foreach ($feature in $config.windowsFeatures) {
        $state = Get-WindowsOptionalFeature -Online -FeatureName $feature
        if ($state.State -ne 'Enabled') {
            # 若以 -NoRestart 抑制重新啟動,是否需要重新啟動會出現在傳回值的 RestartNeeded 中。
            # 若不記錄下來,就會發生「明明需要重新啟動卻以 0 結束」的情況
            $result = Enable-WindowsOptionalFeature -Online -FeatureName $feature -NoRestart
            if ($result.RestartNeeded) { $rebootRequired = $true }
        }
    }

    # --- 4. winget 套件 ----------------------------------------------
    # winget 的結束代碼,即使「已經導入」也可能不是 0;
    # 反過來,即使是 0 實際上也可能沒有安裝。成敗要以查詢狀態來判斷。
    # 若不加上 --scope,會抓到管理員自己以使用者單位導入的紀錄,
    # 誤判為「已在 machine 範圍安裝」
    function Test-KsWingetPackage {
        param([string] $Id, [string] $Scope)
        $arguments = @('list', '--id', $Id, '--exact', '--accept-source-agreements')
        if ($Scope) { $arguments += @('--scope', $Scope) }
        $null = winget @arguments 2>&1
        return ($LASTEXITCODE -eq 0)
    }

    foreach ($package in $config.wingetPackages) {
        if (Test-KsWingetPackage -Id $package.id -Scope $package.scope) { continue }

        # 換行用的反引號要放在行尾。若後面接註解就不算是換行
        winget install --id $package.id -e --silent `
            --accept-package-agreements --accept-source-agreements `
            --scope $package.scope
        $wingetExit = $LASTEXITCODE

        # 這裡如果只顯示警告就繼續往下走,部署工具會把
        # 沒有安裝到必要應用程式的端末記錄成「配置成功」
        if (-not (Test-KsWingetPackage -Id $package.id -Scope $package.scope)) {
            throw "$($package.id) 的導入失敗 (winget ExitCode=$wingetExit)"
        }
    }

    # --- 5. 公司內部應用程式(靜默執行共用資料夾中的安裝程式) ----
    # 已安裝清單要明確開啟 32 位元 / 64 位元兩種檢視。
    # 若 32 位元的 PowerShell 在 64 位元 Windows 上執行(依 Intune 的組態設定可能發生),
    # WOW64 重新導向會使 HKLM:\SOFTWARE\... 指向 32 位元檢視,
    # 把 64 位元的應用程式誤判為「未安裝」而每次都重新安裝一次
    $installedApps = foreach ($view in 'Registry64', 'Registry32') {
        $baseKey = [Microsoft.Win32.RegistryKey]::OpenBaseKey('LocalMachine', $view)
        try {
            $uninstall = $baseKey.OpenSubKey('SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall')
            if (-not $uninstall) { continue }
            try {
                foreach ($name in $uninstall.GetSubKeyNames()) {
                    $appKey = $uninstall.OpenSubKey($name)
                    if (-not $appKey) { continue }
                    try {
                        $displayName = $appKey.GetValue('DisplayName')
                        if ($displayName) {
                            [pscustomobject]@{
                                DisplayName    = [string] $displayName
                                DisplayVersion = [string] $appKey.GetValue('DisplayVersion')
                            }
                        }
                    }
                    finally { $appKey.Dispose() }
                }
            }
            finally { $uninstall.Dispose() }
        }
        finally { $baseKey.Dispose() }
    }

    foreach ($app in $config.internalApps) {
        $installed = $installedApps | Where-Object DisplayName -eq $app.displayName

        # 不只以 DisplayName 一致就判斷為「導入完成」。否則舊版仍在的端末,
        # 新版不會被安裝,即使重新執行也無法收斂到設定檔的狀態。
        # 若設定中有 version,就連是否已安裝該版本以上都一併確認
        $upToDate = if ($app.version) {
            $wanted = [version] $app.version
            [bool]($installed | Where-Object {
                $cur = $_.DisplayVersion -as [version]   # 非版本格式的表示法不列入對象
                $cur -and $cur -ge $wanted
            })
        } else {
            [bool] $installed
        }
        if ($upToDate) { continue }

        # Start-Process 的 -ArgumentList 只是把陣列用空白連接成一行命令,
        # 因此包含空白的值要在設定檔那一側先加上引號
        # 例: '/quiet /norestart INSTALLDIR="C:\Program Files\KsApp"'
        # .msi 不是可執行檔,若直接傳給 Start-Process,
        # 會因「不是有效的應用程式」而失敗。改為透過 msiexec 啟動
        if ([System.IO.Path]::GetExtension($app.installer) -eq '.msi') {
            $msiArgs = @('/i', "`"$($app.installer)`"") + $app.arguments
            $proc = Start-Process -FilePath 'msiexec.exe' -ArgumentList $msiArgs -Wait -PassThru -NoNewWindow
        }
        else {
            $proc = Start-Process -FilePath $app.installer -ArgumentList $app.arguments -Wait -PassThru -NoNewWindow
        }
        # Windows Installer 的結束代碼並非「只有 0 才算成功」。
        # 3010 和 1641 都算成功,差別只在重新啟動的處理方式
        switch ($proc.ExitCode) {
            0    { }                                   # 成功
            3010 { $rebootRequired = $true }           # 成功。需要重新啟動(ERROR_SUCCESS_REBOOT_REQUIRED)
            1641 { $rebootInitiated = $true }          # 成功。安裝程式已開始重新啟動
            default {
                throw "$($app.displayName) 的安裝失敗 (ExitCode=$($proc.ExitCode))"
            }
        }
        # 若重新啟動已經開始,後續的安裝即使執行也會被中斷
        if ($rebootInitiated) { break }
    }

    if ($rebootInitiated) {
        # 1641 是「成功。但已開始重新啟動」。若回傳 0,部署工具會
        # 誤以為「明明完成了卻擅自重新啟動」,因此原樣傳遞
        Write-Host '安裝程式已開始重新啟動。請於重新啟動後再次執行' -ForegroundColor Yellow
        exit 1641
    }

    if ($rebootRequired) {
        # 若原樣回傳 3010,Intune 或部署工具就能解讀為「成功。需要重新啟動」,
        # 進而排程並回報重新啟動。若在此回傳 0,重新啟動就會被遺漏
        Write-Host '配置完成(需要重新啟動)' -ForegroundColor Yellow
        exit 3010
    }

    Write-Host '配置完成' -ForegroundColor Green
    exit 0
}
catch {
    Write-Warning "失敗: $($_.Exception.Message)"
    Write-Warning $_.InvocationInfo.PositionMessage
    exit 1
}
finally {
    Stop-Transcript
}

# 使用者單位的設定(未提升權限,於使用者登入時執行。登錄方式後述)

# 因為是與管理員腳本不同的處理序,所以不會繼承 $config。
# 重新讀取管理員階段時已分發到 ProgramData 的設定
$configPath = 'C:\ProgramData\KsKitting\kitting.config.json'
if (-not (Test-Path $configPath)) {
    Write-Warning "找不到設定檔: $configPath"
    exit 1
}
$config = Get-Content $configPath -Raw -Encoding utf8 | ConvertFrom-Json

# 使用者單位的登錄設定(HideFileExt 等。寫在 HKLM 不會生效)
foreach ($reg in $config.userRegistry) {
    if (-not (Test-Path $reg.key)) { $null = New-Item -Path $reg.key -Force }

    $item   = Get-Item -Path $reg.key
    $exists = $item.GetValueNames() -contains $reg.name
    $same   = $exists -and
              $item.GetValue($reg.name) -eq $reg.value -and
              $item.GetValueKind($reg.name).ToString() -eq $reg.type

    if (-not $same) {
        Set-ItemProperty -Path $reg.key -Name $reg.name -Value $reg.value -Type $reg.type
    }
}

# 網路磁碟機
foreach ($drive in $config.drives) {
    $local    = "$($drive.letter):"
    $existing = Get-SmbMapping -LocalPath $local -ErrorAction SilentlyContinue
    if ($existing) {
        # 若只以「是否已配置」來判斷,即使因共用資料夾搬遷而變更了設定,
        # 舊的配置仍會殘留卻被回報為「成功」。連連線目標都要比較
        if ($existing.RemotePath.TrimEnd('\') -eq $drive.path.TrimEnd('\')) { continue }
        Remove-SmbMapping -LocalPath $local -Force
    }
    New-SmbMapping -LocalPath $local -RemotePath $drive.path -Persistent $true
}

# 連接共用印表機同樣是以使用者為單位。若以管理員或 SYSTEM 執行,
# 只會替該帳戶建立連線,使用者看不到
foreach ($printer in $config.printers) {
    if (-not (Get-Printer -Name $printer.name -ErrorAction SilentlyContinue)) {
        Add-Printer -ConnectionName $printer.connection
    }
}

# 把使用者階段的腳本,放到所有使用者都能讀取的位置
$userScript = 'C:\ProgramData\KsKitting\Invoke-KsUserKitting.ps1'
Copy-Item "$PSScriptRoot\Invoke-KsUserKitting.ps1" $userScript -Force

# HKLM 的 Run 會以登入使用者的權限(未提升權限)執行。
# 即使想寫入 HKCU,既然是以管理員/SYSTEM 執行,寫入的
# 會是「管理員自己的 HKCU」,而不是接下來要使用的員工的 HKCU
$runKey  = 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Run'
$command = 'powershell.exe -NoProfile -ExecutionPolicy Bypass ' +
           "-WindowStyle Hidden -File `"$userScript`""
Set-ItemProperty -Path $runKey -Name 'KsUserKitting' -Value $command

# 放置到所有使用者都能讀取的位置(與方法 1 相同)
$userScript = 'C:\ProgramData\KsKitting\Invoke-KsUserKitting.ps1'
New-Item -ItemType Directory -Path (Split-Path $userScript) -Force | Out-Null
Copy-Item -Path '.\Invoke-KsUserKitting.ps1' -Destination $userScript -Force

$action = New-ScheduledTaskAction -Execute 'powershell.exe' `
    -Argument "-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$userScript`""

$trigger = New-ScheduledTaskTrigger -AtLogOn

# 指定 BUILTIN\Users(S-1-5-32-545)後,會以登入本人的權限執行。
# RunLevel Limited 就是「不提升權限」的指定。若在此改為 Highest,
# 就會在提升權限的工作階段中執行,導致磁碟機配置對使用者不可見
$principal = New-ScheduledTaskPrincipal -GroupId 'S-1-5-32-545' -RunLevel Limited

Register-ScheduledTask -TaskName 'KsUserKitting' `
    -Action $action -Trigger $trigger -Principal $principal -Force

Install-Module -Name Microsoft.WinGet.Client -Scope AllUsers -Force

# 確認是否已導入後再安裝(冪等)
foreach ($id in 'Google.Chrome', 'Microsoft.VisualStudioCode', '7zip.7zip') {
    if (Get-WinGetPackage -Id $id -ErrorAction SilentlyContinue) {
        Write-Verbose "已導入: $id"
        continue
    }
    Install-WinGetPackage -Id $id -Mode Silent -Scope System
}

# 語法解析 + 靜態分析(在 Windows 以外的環境也能執行)
./Invoke-SampleTests.ps1