模板继承与静态资源路径：一次让人崩溃的部署排查记录

上周把一个基于Xiuno二次开发的小项目从本地搬到服务器，结果前端样式全丢，控制台里一堆404。折腾了三个小时，最后发现是模板继承和静态资源发布路径的配合问题。写下来给后来人避坑。

先说结论：当你的模板通过继承方式复用父模板时，静态资源的相对路径解析基准不是当前模板文件，而是入口文件（index.php）所在的目录。这个认知偏差是绝大多数路径问题的根源。

具体场景是这样的：我的自定义模板放在 view/custom/ 下，父模板在 view/default/。子模板里写的是：

<link rel="stylesheet" href="css/app.css">
<script src="js/main.js"></script>

本地开发时一切正常，因为项目根目录正好是Web根目录。但部署到服务器后，我把站点放在了子目录 /blog/ 下，于是浏览器解析出来的路径变成了 /blog/css/app.css，而实际文件在 /blog/view/custom/css/app.css，自然404。

更隐蔽的是，如果父模板里引用了公共资源（比如jQuery、公共样式），子模板继承后这些引用也会一并带过来。父模板里如果用了相对路径，子模板页面加载时同样会错位。我一开始只改了自己写的部分，父模板的公共资源引用没动，结果页面一半有样式一半裸奔，排查起来特别迷惑。

解决办法其实不复杂，推荐两种：

方案一：绝对路径（最省事）
在模板里直接用 {$path} 变量拼接完整路径。Xiuno的模板引擎里，$path 会输出当前应用的根URL，比如 /blog。写法是：

<link rel="stylesheet" href="{$path}/view/custom/css/app.css">

这样无论部署在哪个层级，都能正确指到文件。缺点是要手动写全路径，模板里看起来啰嗦一点。

方案二：用全局配置定义资源域名
在 conf.php 里加一个自定义配置项，比如：

'static_url' => 'https://cdn.example.com/xiuno',

然后在模板里用 {$config['static_url']} 引用。好处是以后换CDN或改目录，只改一处配置就行。适合资源文件比较多的项目。

另外提醒一点：模板继承时，子模板里用 {extends} 和 {block} 的方式引入父模板内容，父模板里所有相对路径的解析都会以最终渲染的页面URL为准，而不是以模板文件位置为准。这是PHP模板引擎的通用行为，不是Xiuno独有的坑。理解了这一点，遇到类似问题就能快速定位。

最后附上我排查时用的快速定位法：直接在浏览器地址栏手动拼路径，如果能打开文件，说明路径本身没问题，问题出在引用方式；如果打不开，检查文件是否真的发布到了服务器对应目录。很多时候是FTP上传漏了文件夹，白排查半天。