日本語ファイル文字化け対策ガイド

1. 最初に決めるべき推奨ルール

ファイル種別ごとの標準

2. なぜ文字化けするのか

典型例：UTF-8の日本語をCP932として読んだ場合

「ユーザーエージェント」というUTF-8文字列を、Windowsの古い日本語コードページ寄りの解釈で読むと、繝ｦ繝ｼ繧ｶ繝ｼ... のような文字化けになります。質問中の例1はこのパターンです。

本来はUTF-8として読むべきバイト列をCP932など別の規則で読むと、PowerShellの switch 句、ハッシュリテラル、引用符、全角記号が壊れ、構文解析エラーになります。

3. S-JIS / UTF-8 / UTF-8 BOM付き / Unicode の違い

BOMのバイト列

4. Windows・各エディタ・PowerShell の関係

全体マトリクス

VS Code の推奨設定例

VS Code全体をUTF-8 BOM付きにすると、Apache/Tomcat設定ファイルにもBOMが入りやすくなります。したがって、全体既定はUTF-8 BOMなしのまま、PowerShellファイルだけBOM付きにする方が安全です。

{
  // 全体は UTF-8 BOMなし
  "files.encoding": "utf8",
  "files.autoGuessEncoding": true,

  // PowerShellだけ UTF-8 BOM付きにしたい場合
  "[powershell]": {
    "files.encoding": "utf8bom"
  }
}

5. Apache / Tomcat の conf・xml を扱う注意点

Apache設定ファイルの実務ルール

Tomcat設定ファイルの実務ルール

6. 文字コード確認方法

PowerShellで先頭BOMを確認する簡易コマンド

# 先頭4バイトを16進表示
$path = ".\sample.ps1"
$bytes = [System.IO.File]::ReadAllBytes((Resolve-Path $path))
[BitConverter]::ToString($bytes[0..([Math]::Min(3, $bytes.Length - 1))])

# 判定例
# EF-BB-BF-xx : UTF-8 BOM付き
# FF-FE-xx-xx : UTF-16 LE
# FE-FF-xx-xx : UTF-16 BE
# それ以外     : UTF-8 BOMなし、CP932、ASCII等の可能性

7. PowerShellでの安全な読み書きサンプル

7.1 Windows PowerShell 5.1 / PowerShell 7 両対応の読み取り方針

Apache/Tomcat/INI/CSVを読むスクリプトは、ファイルの文字コードを決め打ちしない方が安全です。以下の順で判定します。

7.2 安全なテキスト読み取り関数

function Read-TextFileSafe {
    param(
        [Parameter(Mandatory)]
        [string]$Path
    )

    if (-not (Test-Path -LiteralPath $Path)) {
        throw "File not found: $Path"
    }

    $bytes = [System.IO.File]::ReadAllBytes($Path)

    if ($bytes.Length -ge 3 -and
        $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
        $enc = New-Object System.Text.UTF8Encoding($true)
        $text = $enc.GetString($bytes)
    }
    elseif ($bytes.Length -ge 2 -and $bytes[0] -eq 0xFF -and $bytes[1] -eq 0xFE) {
        $text = [System.Text.Encoding]::Unicode.GetString($bytes)
    }
    elseif ($bytes.Length -ge 2 -and $bytes[0] -eq 0xFE -and $bytes[1] -eq 0xFF) {
        $text = [System.Text.Encoding]::BigEndianUnicode.GetString($bytes)
    }
    else {
        # まずBOMなしUTF-8として厳密に読む
        try {
            $utf8Strict = New-Object System.Text.UTF8Encoding($false, $true)
            $text = $utf8Strict.GetString($bytes)
        }
        catch {
            # 日本語Windowsのレガシー想定
            $text = [System.Text.Encoding]::GetEncoding(932).GetString($bytes)
        }
    }

    # 先頭BOMが文字として残った場合の保険
    return ($text -replace "^\uFEFF", "")
}

7.3 INI読み取り時のBOM対策

function Read-IniFileSafe {
    param([Parameter(Mandatory)][string]$Path)

    $content = Read-TextFileSafe -Path $Path
    $result = [ordered]@{}
    $section = ""

    foreach ($rawLine in ($content -split "`r?`n")) {
        $line = $rawLine.Trim()

        if ($line -eq "" -or $line.StartsWith(";") -or $line.StartsWith("#")) {
            continue
        }

        # [Monitor] の前にBOMが紛れた場合も除去
        $line = $line -replace "^\uFEFF", ""

        if ($line -match "^\[(.+)\]$") {
            $section = $Matches[1].Trim()
            if (-not $result.Contains($section)) {
                $result[$section] = [ordered]@{}
            }
            continue
        }

        if ($line -match "^\s*([^=]+?)\s*=\s*(.*)$") {
            if ($section -eq "") {
                $section = "Global"
                if (-not $result.Contains($section)) {
                    $result[$section] = [ordered]@{}
                }
            }
            $key = $Matches[1].Trim()
            $value = $Matches[2].Trim()
            $result[$section][$key] = $value
        }
    }

    return $result
}

7.4 出力時はエンコードを必ず明示

7.5 Windows PowerShell 5.1でUTF-8 BOMなしを書きたい場合

function Write-Utf8NoBom {
    param(
        [Parameter(Mandatory)][string]$Path,
        [Parameter(Mandatory)][string]$Text
    )

    $enc = New-Object System.Text.UTF8Encoding($false)
    [System.IO.File]::WriteAllText($Path, $Text, $enc)
}

function Write-Utf8Bom {
    param(
        [Parameter(Mandatory)][string]$Path,
        [Parameter(Mandatory)][string]$Text
    )

    $enc = New-Object System.Text.UTF8Encoding($true)
    [System.IO.File]::WriteAllText($Path, $Text, $enc)
}

8. ZIPと日本語ファイル名の注意点

ZIPのファイル名は、ZIP作成ツールが「UTF-8ファイル名である」というフラグを正しく立てるか、展開ツールがそれを正しく読むかに依存します。PKWAREの仕様では、General Purpose Bit Flagのbit 11が立っている場合、ファイル名とコメントはUTF-8として扱われます。

ZIP成果物の推奨構成

ApacheLogTool_20260613.zip
├─ README.html                  # 日本語説明はここに集約
├─ manifest.csv                 # 日本語名と英数字ファイル名の対応表
├─ scripts/
│  ├─ Monitor-ApacheLog.ps1     # UTF-8 BOM付き
│  └─ ApacheLogLib.psm1         # UTF-8 BOM付き
├─ conf/
│  └─ monitor.ini               # 仕様に応じてUTF-8 BOM付きまたはBOMなし
└─ sample/
   └─ apache_access_sample.log

9. 症状別の原因と対処

10. チーム運用ルール・チェックリスト

10.1 文字コード標準ルール

10.2 本番反映前チェックリスト

10.3 一括検査用PowerShellサンプル

param(
    [string]$Root = "."
)

$targets = Get-ChildItem -LiteralPath $Root -Recurse -File |
    Where-Object { $_.Extension -in ".ps1",".psm1",".psd1",".conf",".ini",".xml",".properties",".csv",".log",".txt" }

$result = foreach ($f in $targets) {
    $bytes = [System.IO.File]::ReadAllBytes($f.FullName)
    $head = if ($bytes.Length -ge 4) { [BitConverter]::ToString($bytes[0..3]) } else { [BitConverter]::ToString($bytes) }

    $encoding = "UnknownOrNoBOM"
    if ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) { $encoding = "UTF-8 BOM" }
    elseif ($bytes.Length -ge 2 -and $bytes[0] -eq 0xFF -and $bytes[1] -eq 0xFE) { $encoding = "UTF-16 LE" }
    elseif ($bytes.Length -ge 2 -and $bytes[0] -eq 0xFE -and $bytes[1] -eq 0xFF) { $encoding = "UTF-16 BE" }

    $warning = @()
    if ($f.Extension -in ".ps1",".psm1",".psd1" -and $encoding -ne "UTF-8 BOM") {
        $warning += "PowerShell script is not UTF-8 BOM"
    }
    if ($f.Extension -in ".conf",".xml",".properties" -and $encoding -match "UTF-16") {
        $warning += "Config file is UTF-16"
    }
    if ($f.Name -match "[^\x00-\x7F]") {
        $warning += "Non-ASCII file name"
    }

    [pscustomobject]@{
        Path     = $f.FullName
        Ext      = $f.Extension
        Encoding = $encoding
        Head     = $head
        Warning  = ($warning -join "; ")
    }
}

$result | Format-Table -AutoSize

10.4 AIへファイル作成を依頼する時の指定文例

以下のルールでファイルを作成してください。
1. ZIP内のファイル名・フォルダ名は英数字、ハイフン、アンダースコアのみ。
2. 日本語の説明はHTML/README本文に記載し、ファイル名には使わない。
3. PowerShellの .ps1/.psm1 は UTF-8 BOM付きで保存。
4. Apache/Tomcatが読む .conf/.xml は UTF-8 BOMなしで保存。
5. PowerShellスクリプト内の関数名・変数名・ハッシュキーは英数字中心。
6. 日本語ログや日本語列名が必要な場合は、出力直前に付与する。
7. ファイル出力時は必ず -Encoding または .NET Encoding を明示する。

11. 参考情報

• Microsoft Learn: about_Character_Encoding - PowerShell
  https://learn.microsoft.com/ja-jp/powershell/module/microsoft.powershell.core/about/about_character_encoding
• Microsoft Learn: Understanding file encoding in VS Code and PowerShell
  https://learn.microsoft.com/en-us/powershell/scripting/dev-cross-plat/vscode/understanding-file-encoding
• PKWARE APPNOTE.TXT - ZIP File Format Specification
  https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
• Apache HTTP Server Glossary - Configuration File
  https://httpd.apache.org/docs/current/glossary.html
• Apache HTTP Server Core Directives - Include / AddDefaultCharset
  https://httpd.apache.org/docs/current/mod/core.html
• Apache HTTP Server mod_mime - AddCharset
  https://httpd.apache.org/docs/current/mod/mod_mime.html
• Apache Tomcat 9 Configuration Reference - HTTP Connector / URIEncoding
  https://tomcat.apache.org/tomcat-9.0-doc/config/http.html
• サクラエディタ ヘルプ - タイプ別設定『ウィンドウ』プロパティ
  https://sakura-editor.github.io/help/HLP000319.html
• Microsoft Q&A: Windows 10 Notepad encoding options
  https://learn.microsoft.com/en-us/answers/questions/2152989/windows-10-notepad-encoding-options