macOS 环境下的依赖解析与版本锁定策略

macOS下Python依赖管理需通过poetry或pip-tools锁定完整依赖树以确保可重现性：仅venv不够，必须用poetry init、add、install生成poetry.lock锁定所有层级版本与哈希，或用pip-tools的requirements.in配合pip-compile生成带哈希的requirements.txt。

macos 下依赖解析与版本锁定不是“装完包就完事”，而是围绕可重现性和环境一致性建立的一套闭环机制。关键不在于用哪个工具，而在于是否切断了“本地能跑”和“别人/服务器也能跑”之间的不确定性。

Python：用 poetry 或 pip-tools 锁定完整依赖树

仅靠 venv 创建隔离环境远远不够——它不记录间接依赖版本，也不校验哈希。跨机器部署时，pip install -r requirements.txt 仍可能因源、wheel 编译或传递依赖浮动导致行为差异。

• 推荐用 poetry：执行 poetry init 初始化，poetry add requests pandas 添加直接依赖，poetry install 自动创建虚拟环境并生成 poetry.lock，精确锁定所有层级版本与哈希值
• 若需兼容 CI 或遗留流程，用 poetry export -f requirements.txt > requirements.txt 导出带 --hash 的标准格式，确保 pip install -r 完全可验证
• 替代方案 pip-tools：写 requirements.in（只列顶层包），运行 pip-compile --generate-hashes 生成带哈希的 requirements.txt，再 pip install -r

Ruby：靠 Bundler + Gemfile.lock 还原而非安装

macOS 上 Ruby 依赖问题常源于混淆了“系统 Ruby”“Homebrew Ruby”和“rbenv 管理的 Ruby”。真正起作用的是 Gemfile.lock ——它不是日志，而是还原指令。

• 先确认当前 Ruby 归属：which ruby 应指向 ~/.rbenv/shims/ruby，ruby -v 和 gem env home 版本与路径必须一致
• 进入项目后，运行 bundle install（不是 gem install），Bundler 会严格按 Gemfile.lock 中记录的版本、来源和 checksum 安装，跳过解析过程
• 若提示源不可达，用 bundle config set --local mirror.https://rubygems.org https://ruby.taobao.org 切换国内镜像；若 native 扩展编译失败，先装 xcode-select --install

iOS/macOS 原生开发：Podfile.lock 是构建契约

CocoaPods 的 Podfile.lock 不是辅助文件，它是团队协作和 CI 构建的强制契约。只要它存在且被提交，pod install 就不会重新解析版本，而是精确复现。

• pod install 只读取 Podfile.lock，不更改它；只有 pod update 或修改 Podfile 后才会触发新解析并重写 lock 文件
• 多人协作时，禁止删除 Podfile.lock 或跳过提交——哪怕只是“本地试试”，也应 git add Podfile.lock 后再推送
• 遇到冲突报错（如 “Unable to satisfy dependencies”），优先检查 Podfile 中版本约束是否过于宽松（如 ~> 5.0）或过于严苛（如 == 2.1.0），再结合 Podfile.lock 查实际解析结果

通用原则：锁定 ≠ 冻结，而是可控演进

版本锁定不是拒绝更新，而是把“何时更新”“更新到哪”从隐式变成显式。每次变更都该有对应动作和验证。

• 定期执行 poetry update / bundle update / pod update 获取安全补丁和小版本改进，但必须伴随测试通过和 lock 文件提交
• 生产部署前，始终基于 lock 文件还原（poetry install、bundle install --deployment、pod install --repo-update），禁用任何自动解析逻辑
• 所有 lock 文件（poetry.lock、Gemfile.lock、Podfile.lock）必须纳入 Git，且不应手动编辑——它们由工具生成，也应由工具管理