Python 跨平台开发与依赖管理

日期: 2024-11-25 主题: 项目从 Windows 迁移到 Mac 的实践

今天的任务

把 langchain-chatchat 项目从 Windows 迁移到 Mac 环境运行。这个项目是同事在 Windows 上开发的，现在需要在 Mac 上跑起来做进一步开发。

问题一：平台特定依赖

项目的 requirements.txt 里有 pywin32，这是 Windows 专用的包。直接 pip install 会报错。

解决方案：

# 方案1：手动删除
grep -v "pywin32" requirements.txt > requirements_mac.txt
pip install -r requirements_mac.txt

# 方案2：条件依赖（更优雅）
# 在 requirements.txt 中使用环境标记
pywin32==308; sys_platform == 'win32'

如果用 setup.py 或 pyproject.toml，可以更规范地处理：

# setup.py
install_requires = [
    'common_package',
]
extras_require = {
    ':sys_platform == "win32"': ['pywin32'],
}

问题二：SSL 证书

公司网络环境比较特殊，pip 安装时报 SSL 证书验证失败。

解决方案：

# 使用国内镜像 + 信任主机
pip install -r requirements.txt \
    -i https://pypi.tuna.tsinghua.edu.cn/simple \
    --trusted-host pypi.tuna.tsinghua.edu.cn

# 或者更新 certifi
pip install --upgrade certifi

问题三：版本冲突

项目依赖的某些包版本和 Mac 上已安装的版本冲突。这就是为什么一定要用虚拟环境的原因。

# 清理重建虚拟环境
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements_mac.txt

包管理工具演进

今天顺便研究了一下 Python 包管理工具的发展：

pip (基础包管理)
    ↓
virtualenv (环境隔离)
    ↓
venv (Python 3.3+ 内置)
    ↓
pipenv (依赖锁定)
    ↓
poetry (现代化依赖管理)

Poetry 看起来是最现代的选择：

依赖解析更智能
自动生成 lock 文件
pyproject.toml 统一配置

有空要学一下 Poetry。

跨平台开发最佳实践

1. 识别平台特定代码

import platform

if platform.system() == 'Windows':
    import pywin32
    # Windows 特定逻辑
else:
    # 其他平台的替代逻辑
    pass

2. 使用抽象层

把平台相关的操作封装起来：

# platform_utils.py
import platform

def get_home_dir():
    if platform.system() == 'Windows':
        return os.environ.get('USERPROFILE')
    else:
        return os.environ.get('HOME')

3. CI/CD 多平台测试

# GitHub Actions 示例
strategy:
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]

依赖管理要点

实践	说明
使用虚拟环境	隔离项目依赖，避免全局污染
锁定版本	生产环境用 `==` 精确锁定
分离开发依赖	测试工具放在 requirements-dev.txt
条件依赖	平台特定包用环境标记
定期更新	及时修复安全漏洞

今日反思

今天最大的收获是理解了跨平台开发的复杂性。

以前觉得 Python 是跨平台的，代码写一遍到处跑。实际上很多库有平台限制，环境配置也有差异。写代码的时候要时刻考虑兼容性，不能只在自己电脑上能跑就行。

另一个体会是：工具链的选择很重要。pip + venv 能用，但 Poetry 这样的现代工具能省很多麻烦。选择好的工具可以避免很多问题。

下次接手别人的项目，第一件事就是检查依赖有没有平台特定的包。

延伸学习

Poetry 的使用
pyproject.toml 规范（PEP 517/518）
GitHub Actions 多平台 CI
Python 打包和分发

FilesExpand file tree

9.md

Latest commit

History