クロスプラットフォーム互換性

目次

• 概要
• 使用場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

Windows、macOS、Linux にシームレスに対応するコードの書き方に関する包括的ガイドです。ファイルパスの処理、環境検出、プラットフォーム固有の機能、テスト戦略をカバーしています。

使用場面

• 複数のオペレーティングシステム向けアプリケーション開発
• ファイルシステム操作の処理
• プラットフォーム固有の依存関係管理
• オペレーティングシステムおよびアーキテクチャの検出
• 環境変数の操作
• クロスプラットフォーム CLI ツール構築
• 改行コードと文字エンコーディングの処理
• プラットフォーム固有のビルドプロセス管理

クイックスタート

最小限の実装例:

// ❌ BAD: プラットフォーム固有のセパレータがハードコードされたパス
const configPath = "C:\\Users\\user\\config.json"; // Windows のみ
const dataPath = "/home/user/data.txt"; // Unix のみ

// ✅ GOOD: path モジュールを使用
import path from "path";
import os from "os";

// プラットフォームに依存しないパス構築
const configPath = path.join(os.homedir(), "config", "app.json");
const dataPath = path.join(process.cwd(), "data", "users.txt");

// 相対パスを解決
const absolutePath = path.resolve("./config/settings.json");

// パスコンポーネントを取得
const dirname = path.dirname("/path/to/file.txt"); // '/path/to'
const basename = path.basename("/path/to/file.txt"); // 'file.txt'
const extname = path.extname("/path/to/file.txt"); // '.txt'

// パスを正規化 (.. と . を処理)
const normalized = path.normalize("/path/to/../file.txt"); // '/path/file.txt'

リファレンスガイド

references/ ディレクトリの詳細な実装:

ガイド	内容
ファイルパス処理	ファイルパス処理
プラットフォーム検出	プラットフォーム検出
改行コード	改行コード
環境変数	環境変数
シェルコマンド	シェルコマンド
ファイルパーミッション	ファイルパーミッション
プロセス管理	プロセス管理
プラットフォーム固有の依存関係	プラットフォーム固有の依存関係
複数プラットフォームでのテスト	複数プラットフォームでのテスト
文字エンコーディング	文字エンコーディング
ビルド設定	ビルド設定

ベストプラクティス

✅ すべきこと

• パスに path.join() または path.resolve() を使用する
• 改行コードに os.EOL を使用する
• 必要に応じて実行時にプラットフォームを検出する
• すべてのターゲットプラットフォームでテストする
• プラットフォーム固有モジュールに optionalDependencies を使用する
• ファイルパーミッションを適切に処理する
• ユーザー入力にはシェルエスケープを使用する
• テキストファイルの改行コードを正規化する
• デフォルトで UTF-8 エンコーディングを使用する
• プラットフォーム固有の動作を文書化する
• プラットフォーム固有機能のフォールバックを提供する
• CI/CD を使用して複数プラットフォームでテストする

❌ すべきではないこと

• バックスラッシュまたはフォワードスラッシュをハードコードしたファイルパス
• Unix のみの機能を仮定する (シグナル、パーミッション、シンボリックリンク)
• Windows 固有の特性を無視する (ドライブレター、UNC パス)
• フォールバックなしでプラットフォーム固有コマンドを使用する
• ファイルシステムが大文字小文字を区別することを仮定する
• 改行コードの違いを忘れる
• チェックなしでプラットフォーム固有 API を使用する
• 環境変数アクセスパターンをハードコードする
• 文字エンコーディングの問題を無視する