The Turing Way项目基础设施迁移：从Netlify到GitHub Pages的技术决策

背景与挑战

The Turing Way项目当前使用Netlify作为文档构建和托管平台，但随着技术栈的演进，遇到了几个关键挑战：

1. Python版本限制：Netlify仅支持Python 3.8，这导致无法使用最新版本的JupyterBook/Sphinx，且存在潜在的兼容性问题
2. 依赖管理问题：未锁定的依赖包导致CI和Netlify构建过程频繁中断
3. 开源理念冲突：Netlify是闭源服务，与项目的开源理念不完全契合

解决方案评估

项目团队对多个替代方案进行了全面评估：

1. Read The Docs(RTD)方案

优势：

• 专为文档项目设计的开源平台
• 内置版本控制、多格式导出等功能
• 支持现代Python版本(3.12)

劣势：

• 引入自身依赖和插件，可能造成构建环境不一致
• 本地复现问题较困难
• 对翻译功能的支持尚不明确

2. GitHub Pages方案

优势：

• 完全控制构建环境
• 与现有GitHub生态无缝集成
• 使用标准tox.ini配置，保证本地/CI环境一致性

劣势：

• 需要自行实现部署预览功能
• 语言版本管理需要额外开发

3. 其他方案

包括自托管、云存储等方案因迁移成本高或功能不足被排除。

技术实现路径

经过讨论，团队倾向于GitHub Pages方案，并已完成初步验证：

1. 基础部署：

   • 创建GitHub Actions工作流自动构建和发布
   • 配置仓库设置授予工作流读写权限
   • 采用"从分支部署"模式

2. 预览系统：

   • 计划使用pr-preview-action等工具实现PR预览
   • 通过CI自动生成预览链接并评论到PR

3. 多语言支持：

   • 考虑子域名(fr.book.the-turing-way.org)或路径(book.the-turing-way.org/fr)方案
   • 评估是否需要自定义语言选择器

决策考量因素

最终决策基于以下核心原则：

1. 技术可控性：优先选择能完全控制构建环境的方案
2. 开源一致性：尽可能使用开源工具链
3. 维护可持续性：降低对特定维护者的依赖
4. 用户体验：保留必要的预览和语言功能

迁移路线图

1. 完善GitHub Pages部署流程
2. 实现PR预览功能
3. 解决多语言部署问题
4. 文档化迁移过程和维护指南
5. 正式切换并关闭Netlify服务

这一迁移将使The Turing Way项目获得更现代的Python支持、更可控的构建环境，同时保持关键用户体验不变，为项目长期发展奠定更稳固的技术基础。