如何将非Umbrella结构的Phoenix框架项目转为Umbrella模式？

我之前帮朋友处理过一模一样的需求，只要跟着下面的步骤一步步来，就能顺利把你的Phoenix项目转换成Umbrella模式。话不多说，直接上操作流程：

第一步：搭建Umbrella项目骨架 #

先找个合适的位置（比如现有项目的同级目录），创建一个全新的Umbrella根项目：

mix new my_umbrella_app --umbrella

这里的my_umbrella_app是你最终的Umbrella根目录名，换成你自己喜欢的名字就行。

第二步：迁移现有代码到子应用目录 #

进入刚创建的Umbrella根目录，里面有个apps文件夹——这就是我们放所有子应用的地方：

• 如果你的现有项目已经是类似lib/my_app（核心业务）和lib/my_app_web（Web层）的拆分结构：直接把这两个文件夹分别复制到apps/my_app/lib/my_app和apps/my_app_web/lib/my_app_web，同时把现有项目里的priv目录（比如Ecto迁移文件、静态资源）对应复制到各自子应用的priv文件夹下。
• 如果你的代码还没拆分：可以先在apps目录下创建两个子应用（业务核心+Web层），再把代码分别挪进去：

  cd apps
  mix new my_app  # 核心业务子应用
  mix phx.new my_app_web --no-ecto --no-gettext  # 根据你现有项目情况调整参数，比如用了Ecto就去掉--no-ecto
  

另外，别忘了把现有项目的test目录也拆分到对应的子应用test文件夹里。

第三步：调整依赖配置 #

Umbrella的依赖分全局和子应用两级，得把原来的依赖重新梳理：

• 根目录的mix.exs：放所有子应用共享的依赖（比如ecto_sql、postgrex），同时确保apps_path: "apps"这个配置已经存在（创建Umbrella项目时默认会加）。
• 子应用的mix.exs：只保留该应用专属的依赖，比如my_app_web需要phoenix、phoenix_html，my_app保留业务相关的依赖。另外，子应用之间如果有依赖（比如Web层依赖核心业务），要在deps里加上：

  {:my_app, in_umbrella: true}
  

第四步：调整配置文件 #

原来的config目录也要拆分：

• 根目录的config：放全局配置，比如数据库连接、环境变量，子应用可以直接读取这些配置。
• 子应用的config（如果需要）：放该应用专属的配置，比如my_app_web的端点、路由配置。
  注意子应用的配置里要正确引用全局配置，比如my_app_web里调用数据库时，用Application.get_env(:my_app, MyApp.Repo)来获取连接信息。

第五步：调整端点和路由 #

如果原来的Web端点在lib/my_app_web/endpoint.ex，现在它在apps/my_app_web/lib/my_app_web/endpoint.ex，要做两个小调整：

• 确保端点的模块名正确（还是MyAppWeb.Endpoint，不用改，只要路径对就行）
• 在根目录的config/runtime.exs里加上启动端点的代码：

  MyAppWeb.Endpoint.start_link([])
  

第六步：测试验证 #

全部调整完后，在Umbrella根目录跑几个命令验证：

mix deps.get  # 拉取所有依赖
mix test      # 确保所有测试用例通过
iex -S mix phx.server  # 启动服务器，检查功能是否正常

几点注意事项 #

• 操作前一定要用Git提交现有代码的全部状态，做好备份，避免操作失误丢失代码。
• 如果你的项目有自定义的Mix任务，要把它们移到对应的子应用或者根目录的lib/mix/tasks下。
• 尽量保持原有模块名不变，这样能减少代码修改量，降低出错概率。

内容的提问来源于stack exchange，提问作者online