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/ 目录中的详细实现：

指南	内容
文件路径处理	文件路径处理
平台检测	平台检测
换行符	换行符
环境变量	环境变量
Shell 命令	Shell 命令
文件权限	文件权限
进程管理	进程管理
平台特定依赖项	平台特定依赖项
跨平台测试	跨平台测试
字符编码	字符编码
构建配置	构建配置

最佳实践

✅ 应该

• 使用 path.join() 或 path.resolve() 处理路径
• 使用 os.EOL 表示换行符
• 在需要时于运行时检测平台
• 在所有目标平台上进行测试
• 对平台特定模块使用 optionalDependencies
• 妥善处理文件权限
• 对用户输入进行 Shell 转义
• 规范化文本文件中的换行符
• 默认使用 UTF-8 编码
• 记录平台特定行为
• 为平台特定功能提供回退方案
• 使用 CI/CD 在多个平台上进行测试

❌ 不应该

• 使用反斜杠或正斜杠硬编码文件路径
• 假定只有 Unix 才有的功能（信号、权限、符号链接）
• 忽略 Windows 特有的情况（盘符、UNC 路径）
• 使用平台特定命令却不提供回退方案
• 假定文件系统区分大小写
• 忽略不同的换行符
• 不经检查就使用平台特定 API
• 硬编码环境变量的访问方式
• 忽略字符编码问题