TrestleAdmin 从 0.9 升级到 0.10 的注意事项与解决方案

升级背景

TrestleAdmin 是一个优秀的 Rails 后台管理框架，在从 0.9 版本升级到 0.10 版本时，开发者可能会遇到一些兼容性问题。本文将详细介绍升级过程中可能遇到的问题及其解决方案。

主要变更点

1. 资源文件加载问题

在 0.10 版本中，FontAwesome 的字体文件路径发生了变化。如果升级后出现类似"ActionController::RoutingError (No route matches [GET] "/fa-solid-900.ttf")"的错误，可以尝试以下解决方案：

• 确保 Sprockets 配置正确
• 清除旧的资源缓存：

  rails assets:clobber
  rails tmp:cache:clear
  

2. 主题系统重构

0.10 版本对主题系统进行了重大改进，移除了对 Sass 编译器的依赖。新的主题配置方式如下：

• 在 config/initializers/trestle.rb 中定义主色调：

  config.theme = { primary: "#338ab7", secondary: "#719dc3" }
  

• 自定义样式应迁移到 app/assets/stylesheets/trestle/custom.css

3. 路由与请求方法变更

0.10 版本开始全面支持 Turbo，因此原有的 Rails-UJS 风格的请求方法需要更新：

• 旧方式（不再适用）：

  method: :post
  

• 新方式：

  data: { turbo_method: :post }
  

自定义路由问题排查

如果自定义路由在升级后失效，建议：

1. 使用 rails routes 命令确认路由是否存在
2. 检查视图中的链接是否使用了正确的 Turbo 方法
3. 确保控制器动作定义正确

最佳实践

• 升级前备份现有配置
• 分步骤测试各个功能模块
• 优先处理关键业务功能
• 全面测试后再部署到生产环境

总结

TrestleAdmin 0.10 版本带来了现代化的改进，虽然升级过程中可能会遇到一些兼容性问题，但通过本文提供的解决方案，开发者可以顺利完成升级并享受新版本带来的优势。