処理の問題

ファイル処理とパフォーマンスに関するトラブルシューティング

ファイル処理、パフォーマンス、その他の実行時の問題とその解決方法を説明します。

ファイル処理関連

ファイルが処理されない

症状: 処理対象ファイルが0件と表示される。

原因: フィルタ条件が厳しすぎる、または対象ファイルが存在しません。

解決方法:

方法1: ディレクトリを確認:

ls /path/to/images

方法2: 拡張子を確認:

# 対応している拡張子を明示的に指定
lightfile-shot /path/to/images --ext .jpg,.jpeg,.jfif,.png

方法3: ファイルサイズを確認:

# サイズ制限を緩和
lightfile-shot /path/to/images --min-size 1kb --max-size 100mb

方法4: ドライランで確認:

lightfile-shot /path/to/images --dry-run --verbose

ファイルの最適化に失敗

症状:

ファイルの最適化に失敗しました: /path/to/image.jpg (エラー: unsupported format)

原因: ファイルが破損している、またはサポートされていない形式です。

解決方法:

方法1: ファイルが実際に画像ファイルか確認:

file /path/to/image.jpg

方法2: ファイルが破損していないか確認:

# macOS/Linux
identify /path/to/image.jpg  # ImageMagickが必要

方法3: 別の画像ビューアで開けるか確認

ファイルの書き込みに失敗

症状:

最適化されたファイルの書き出しに失敗しました: /path/to/image.jpg

原因: ディスク容量不足、またはファイルのパーミッション不足です。

解決方法:

方法1: ディスク容量を確認:

# Linux/macOS
df -h /path/to/images

# Windows
dir /path/to/images

方法2: パーミッションを確認:

# Linux/macOS
ls -l /path/to/image.jpg

# 書き込み権限を付与
chmod u+w /path/to/image.jpg

方法3: 複製モードで試す（安全）:

lightfile-shot /path/to/images /tmp/output

すべてのファイルがスキップされる

症状: すべてのファイルが「既に最適化されています」とスキップされる。

原因: ファイルがすでに最適化されている、または最適化の余地がありません。

解決方法:

方法1: 品質設定を変更:

# より強力な圧縮を試す
lightfile-shot /path/to/images --quality low

方法2: 詳細ログで確認:

lightfile-shot /path/to/images --verbose

方法3: ジャーナルで詳細を確認:

lightfile-shot /path/to/images --journal result.ndjson
grep 'skipped' result.ndjson

パフォーマンス関連

処理が遅い

症状: 処理に時間がかかりすぎる。

解決方法:

方法1: 並列処理を有効化:

# CPUコア数に合わせる（例: 4コアの場合）
lightfile-shot /path/to/images --concurrency 4

方法2: ファイルサイズでフィルタ:

# 大きなファイルのみ処理（効果が大きい）
lightfile-shot /path/to/images --min-size 100kb

方法3: 詳細ログを無効化:

# ログレベルを下げる
lightfile-shot /path/to/images --log-level warn

メモリ不足

症状: プログラムが途中で停止する、またはシステムが重くなる。

解決方法:

方法1: 並列処理数を減らす:

# 並列処理を控えめに
lightfile-shot /path/to/images --concurrency 1

方法2: 大きなファイルを除外:

# 5MB以下のファイルのみ処理
lightfile-shot /path/to/images --max-size 5mb

方法3: バッチ処理:

# ディレクトリごとに分けて処理
lightfile-shot /path/to/images/dir1 --concurrency 2
lightfile-shot /path/to/images/dir2 --concurrency 2

その他の問題

進捗が更新されない

症状: 進捗表示がフリーズしているように見える。

原因: 大きなファイルの処理中、または並列処理数が多すぎる場合に発生することがあります。

解決方法:

方法1: 詳細ログで確認:

lightfile-shot /path/to/images --verbose

方法2: 並列処理数を調整:

lightfile-shot /path/to/images --concurrency 2

方法3: プロセスが動いているか確認:

# Linux/macOS
ps aux | grep lightfile-shot

# Windows
tasklist | findstr lightfile-shot

Ctrl+C で止まらない

症状: Ctrl+C を押しても処理が終了しない。

原因: 処理中のファイルが完了するまで待機しています。

解決方法:

現在処理中のファイルが完了するまで待ってください（通常数秒〜数十秒）

どうしてもすぐに止めたい場合は、プロセスを強制終了:

# Linux/macOS
killall -9 lightfile-shot

# Windows
taskkill /F /IM lightfile-shot.exe

注意: 強制終了すると、処理中のファイルが破損する可能性があります。

トラブルシューティングのベストプラクティス

ドライランで確認

実際の処理を行う前に、ドライランモードで動作を確認します:

lightfile-shot /path/to/images --dry-run --verbose

詳細ログを有効化

問題が発生した場合は、詳細ログを有効にして原因を特定します:

lightfile-shot /path/to/images --log-level debug --verbose

ジャーナルで記録

処理結果を詳細に記録して、後から分析できるようにします:

lightfile-shot /path/to/images --journal result.ndjson

ジャーナルの活用方法はジャーナル機能を参照してください。

段階的に設定を追加

設定を段階的に追加して、問題の箇所を特定します:

# 1. 最もシンプルな実行
lightfile-shot /path/to/images

# 2. フィルタを追加
lightfile-shot /path/to/images --min-size 10kb

# 3. 品質設定を追加
lightfile-shot /path/to/images --min-size 10kb --quality high

# 4. 並列処理を追加
lightfile-shot /path/to/images --min-size 10kb --quality high --concurrency 4

サポート

問題が解決しない場合は、以下の情報を含めて報告してください:

lightfile-shotのバージョン (lightfile-shot --version)
OS とバージョン
実行したコマンド
エラーメッセージ全文
--verbose --log-level debug での出力

目次