VSCode跨平台开发需手动对齐五处：环境路径、Shell集成、终端行为、调试器路径和扩展兼容性，否则配置无法复用；须统一终端Shell与PATH、launch.json用${workspaceFolder}等变量、Python解释器动态选择、Git换行符用.gitattributes规范、扩展二进制依赖需各平台单独验证。
vscode 本身是跨平台的，但「跨平台开发配置」不是开箱即用——关键在于环境路径、shell 集成、终端行为、调试器路径和扩展兼容性这五处必须手动对齐，否则你在 mac 上能跑通的 launch.json，到 linux 上大概率报 cannot find runtime 'node' 或 command 'python.pythonpath' not found。
统一终端 Shell 和 PATH 行为
VSCode 的集成终端（Ctrl+`）在不同系统默认调用不同 Shell：Windows 是 PowerShell 或 CMD，macOS 是 zsh，Linux 多为 bash/zsh。但真正影响开发的是 $PATH 是否包含你安装的工具链（如 node、python3、rustc）。
- 不要依赖系统默认 Shell 的初始化文件（如
~/.zshrc）自动加载 PATH —— VSCode 终端有时不读取它们，尤其在 GUI 启动时 - 在 VSCode 设置中显式指定终端 profile：
"terminal.integrated.profiles.windows"、"terminal.integrated.profiles.osx"、"terminal.integrated.profiles.linux"，并确保每个 profile 的env字段补全关键路径，例如 Linux 下加"PATH": "/home/you/.local/bin:/opt/rust/bin:${env:PATH}" - 验证方式：打开新终端，运行
which node和echo $PATH，确认输出与命令行终端一致
调试配置（launch.json）避免硬编码路径
launch.json 里写死 "program": "C:\src\app.js" 或 "program": "/Users/name/app.js" 会导致配置无法复用。VSCode 提供了跨平台变量，但很多人漏用了 ${env:HOME} 或误用 ${workspaceFolder}。
- 永远用
${workspaceFolder}替代绝对路径，它在 Windows/macOS/Linux 下自动转义为对应格式（如C:\proj//Users/name/proj//home/name/proj） - 需要用户主目录时，用
${env:HOME}（Linux/macOS）或${env:USERPROFILE}（Windows），不要混用；更稳妥的是统一用${env:HOME}—— Windows 上 VSCode 也支持该变量（只要系统设置了HOME环境变量） - Node.js 调试中，
"runtimeExecutable"别写"C:\Program Files\nodejs\node.exe"，改用"${env:PATH} 中第一个 node"即留空，让 VSCode 自动探测
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch app",
"program": "${workspaceFolder}/src/index.js",
"env": {
"NODE_ENV": "development"
}
}
]
}Python 扩展的解释器路径必须动态选择
Python 扩展（ms-python.python）会缓存上次选中的 python.pythonPath，而这个路径在不同系统上完全不同。手动切换不仅麻烦，还容易在共享项目时污染 .vscode/settings.json。
- 删除
settings.json中所有硬编码的"python.pythonPath"字段 —— 它已被弃用，新版用"python.defaultInterpreterPath"，但仍不推荐写死 - 改用工作区级 Python 解释器选择：按
Cmd+Shift+P（Mac）或Ctrl+Shift+P（Win/Linux），输入Python: Select Interpreter，然后选Enter interpreter path...，再填${env:HOME}/.pyenv/versions/3.11.5/bin/python（macOS/Linux）或${env:USERPROFILE}\.pyenv\versions\3.11.5\Scripts\python.exe（Windows） - 如果用 conda，优先选
Conda Environment类型，它比路径字符串更稳定
Git 配置与换行符（CRLF vs LF）要全局对齐
Windows 默认用 CRLF（
），macOS/Linux 用 LF（
）。VSCode 的 files.eol 设置只影响编辑器保存行为，不影响 Git 提交和检出逻辑 —— 这才是跨平台协作出问题的根源。
- 在项目根目录加
.gitattributes，强制规范换行符：* text=auto eol=lf（全部文本用 LF），或更细粒度地写*.py text eol=lf、*.bat text eol=crlf - 全局设置 Git 换行策略：
git config --global core.autocrlf input（Linux/macOS 推荐），Windows 用户可用git config --global core.autocrlf true，但必须和.gitattributes配合，否则冲突 - VSCode 状态栏右下角显示当前 EOL 模式，点击可切换；但切完后务必检查是否触发了大量“修改”文件 —— 如果有，说明本地 Git 配置和文件实际换行不一致，需先
git add --renormalize .
最常被忽略的是：VSCode 的「设置同步」（Settings Sync）不会同步已安装的扩展二进制依赖（比如 C/C++ 扩展的 cpptools server、Go 扩展的 gopls），这些必须在每台机器上单独安装并验证版本一致。别信「同步完设置就万事大吉」—— 先 which gopls，再 gopls version，三台机器对齐了才算真跨平台。
