引入phug(pug-php/pug)的PHP项目该如何调整原有目录结构？

不用大动原有项目的基础框架，只要在原结构上做几处适配就能跑通phug的开发流程，核心是把原有的PHP HTML视图层替换为pug源模板管理，同时单独划出编译缓存的存储路径，避免和业务源码混放。

具体目录调整动作 #

• 完整保留原有src/library、根目录css、src/index.php的位置和用途：这部分是业务逻辑、静态资源、入口文件的核心，和模板引擎适配无关，不需要做任何改动。
• 改造src/views目录：原来这里存放带HTML的PHP视图文件，现在统一改成存放pug模板源码，所有页面骨架、公共布局、可复用组件全部用.pug后缀的文件存在这个目录下；可以在目录内按需拆分子文件夹，比如放全局页头页脚骨架的layouts、放通用交互组件的partials、放具体业务页面的pages，不再在这个目录下写混HTML的PHP视图。
• 新增专属缓存目录：在项目根目录创建storage/cache/phug文件夹，给PHP进程开通读写权限，专门用来存储phug把pug模板编译成可执行PHP文件的缓存；绝对不能把缓存目录和pug源文件放在同一个文件夹里，不然既容易误改编译产物，后期清理缓存也找不到对应路径。
• 安装phug依赖后会自动生成vendor目录，所有第三方库的加载直接走这个目录的自动加载规则，不用额外手动写路径引入phug的核心代码。

调整后的完整参考目录结构 #

project
 |- css (原有静态样式目录，后续可按需扩展js、images等同级静态资源目录)
 |- storage
 |  |- cache
 |  |  |- phug (phug编译缓存专用目录，需配置读写权限)
 |- src
 |  |- library (原有后端交互逻辑库，无UI代码，完全保留)
 |  |- views (pug模板源目录，替换原PHP格式的HTML视图)
 |  |  |- layouts (通用布局模板，比如全局页头页脚骨架)
 |  |  |- partials (可复用页面组件，比如导航栏、信息卡片块)
 |  |  |- pages (各业务页面对应的pug模板)
 |  |- index.php (项目入口，负责初始化phug实例、绑定路由渲染对应模板)
 |- vendor (composer自动生成的第三方依赖目录)

实际开发的注意要点 #

• 入口index.php里初始化phug实例时，要明确指定两个核心路径：模板根路径指向src/views，缓存路径指向storage/cache/phug；开发环境可以开启debug模式，修改pug文件后自动触发重新编译，生产环境关闭debug直接走缓存，减少不必要的编译开销。
• 不要在src/views目录下存放任何编译生成的PHP缓存文件，所有编译产物统一放到专门的storage缓存目录，从结构上避免源文件和产物混淆的问题。
• 原来在PHP视图里混写的业务逻辑，统一抽离到src/library的后端逻辑代码里，只把需要渲染到页面的变量传给pug模板做插值渲染，保持模板层的职责单一。

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