Python跨环境运行需控制依赖、规避平台差异、统一执行上下文：用pip-compile锁定版本，pathlib处理路径，纯Python替代系统命令，显式声明Python版本并矩阵测试。
Python代码跨环境运行不难，但容易因细节疏忽导致失败。核心在于控制依赖、规避平台差异、统一执行上下文。
依赖管理要精确锁定版本
不同环境中 pip install 未指定版本，可能装上不兼容的包。用 requirements.txt 锁定所有依赖及其子依赖版本：
- 生成时用
pip freeze > requirements.txt（仅适用于开发机环境干净时） - 更稳妥的方式是用
pip-compile（来自 pip-tools），从 requirements.in 编译出带哈希和完整依赖树的 requirements.txt - 避免在代码中用
pip install动态装包；部署时统一用pip install --no-deps -r requirements.txt配合虚拟环境
路径与文件系统需平台中立
Windows 用反斜杠 \，Linux/macOS 用正斜杠 /，硬编码路径必然出错：
- 一律使用
os.path.join()或更推荐的pathlib.Path构造路径，例如Path("data") / "config.json" - 读写文件时避免假设当前工作目录（cwd），用
__file__定位脚本所在目录再拼接，如Path(__file__).parent / "conf.yaml" - 临时文件用
tempfile模块生成，不要写死/tmp或C:\temp
系统命令与环境变量不可硬编码
调用 subprocess.run(["ls", "-l"]) 在 Windows 上直接报错；依赖 PATH 中存在某个工具也极不可靠：
huaweicloud-python-sdk-helper
下载
华为云 Python SDK 查询工具。自动发现已安装 SDK 的服务包、Client类、API 方法、入参详情、类信息（__init__ 参数、属性、类型、描述），支持关键字搜索，快速定位目标 API 使用方法。
立即学习“Python免费学习笔记（深入）”；
- 优先用纯 Python 替代方案（如
os.listdir()代替ls，shutil.copy()代替cp） - 必须调外部命令时，检查
sys.platform或用shutil.which()判断工具是否存在，提供降级逻辑 - 环境变量读取用
os.getenv("VAR_NAME", "default")，不假设变量一定存在；敏感配置改用配置文件或专用库（如python-decouple）
Python 版本与语法兼容性要明确声明
3.8 的 math.lcm() 在 3.7 不可用；f-string 调试语法 f"{x=}" 仅限 3.8+
- 在 pyproject.toml 或 setup.py 中声明
python_requires=">=3.8"，让 pip 安装时自动拦截低版本环境 - CI 流程中至少跑两个主流版本（如 3.9 和 3.12），用
tox或 GitHub Actions 矩阵测试 - 避免使用
typing中已废弃的写法（如typing.List），优先用内置类型注解（list[int]），并设from __future__ import annotations保证前向兼容
可移植不是追求“一次编写到处运行”，而是让每次迁移都有明确预期和可控路径。关键在自动化验证、显式声明约束、拒绝隐式假设。
