cross-platform-compatibility

クロスプラットフォーム対応

目次

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

概要

Windows、macOS、Linux でシームレスに動作するコードを書くための包括的なガイドです。ファイルパスの処理、環境の検出、プラットフォーム固有の機能、テスト戦略を扱います。

使用する場面

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

クイックスタート

最小限の実行可能な例：

// ❌ BAD: Hardcoded paths with platform-specific separators
const configPath = "C:\\Users\\user\\config.json"; // Windows only
const dataPath = "/home/user/data.txt"; // Unix only

// ✅ GOOD: Use path module
import path from "path";
import os from "os";

// Platform-independent path construction
const configPath = path.join(os.homedir(), "config", "app.json");
const dataPath = path.join(process.cwd(), "data", "users.txt");

// Resolve relative paths
const absolutePath = path.resolve("./config/settings.json");

// Get path components
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'

// Normalize paths (handle .. and .)
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 を使用する
• 環境変数へのアクセス方法をハードコードする
• 文字エンコーディングの問題を無視する