必须确保Webpack输出路径、publicPath和版本哈希三者严格一致，否则页面白屏或样式丢失；需检查setOutputPath指向public/build/且setPublicPath('/build')为相对前缀，并通过encore_entry_*（Symfony）、mix()（Laravel）或自定义asset()函数动态读取manifest.json解析哈希路径。
PHP框架中引用Webpack打包后的带哈希文件时，必须让模板引擎生成的HTML中<script>和<link>标签的src/href路径与实际输出位置、publicPath、版本哈希三者严格一致，否则页面白屏或样式丢失。</script>
确认Webpack输出路径与publicPath匹配
打开webpack.config.js，检查两处关键配置是否协同：
第一，【setOutputPath 必须指向 public/build/】——Symfony等主流PHP框架默认只公开public/子目录，若设为dist/或build/（无public前缀），浏览器请求资源必404。
第二，setPublicPath('/build')必须是相对URL前缀，不能带协议和域名，也不能以./开头；它会直接拼在所有资源URL前面，例如最终生成/build/app.a1b2c3.js。
立即学习“PHP免费学习笔记（深入）”；
这两项不一致，PHP模板里调用任何函数都救不回来。
Symfony中用encore_entry_*函数自动注入
确保已安装@symfony/webpack-encore并启用enableVersioning(Encore.isProduction())。
在Twig模板中，用以下方式引入资源：
{{ encore_entry_script_tags('app') }} → 输出带完整路径和哈希的<script>标签
{{ encore_entry_link_tags('app') }} → 输出对应的<link rel="stylesheet">
注意：参数'app'必须与addEntry('app', './assets/js/app.js')中第一个字符串完全一致，大小写敏感，多一个空格就找不到入口。
Laravel中手动拼接需同步manifest.json
Laravel不内置Webpack路径解析器，必须依赖mix()辅助函数或自行读取public/mix-manifest.json。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
方法一：使用Laravel Mix（推荐）
在webpack.mix.js中调用.version()，构建后生成mix-manifest.json；模板中写{{ mix('js/app.js') }}，它会自动查表替换为/js/app.js?id=abc123。
方法二：纯Webpack项目手动处理
启用webpack-manifest-plugin，配置输出manifest.json到public/build/；PHP中用json_decode(file_get_contents(public_path('build/manifest.json')))读取映射，再拼出完整URL。
⚠️ 不要硬编码/build/app.js——哈希变更后链接立刻失效，且开发环境常禁用哈希，必须动态读取。
自定义PHP框架：用asset()函数封装路径逻辑
第一步：在PHP公共函数库中定义asset()，支持环境判断：
开发环境直接返回/build/{$file}；生产环境先读public/build/manifest.json，用键查找对应值，找不到则退化为原路径。
第二步：确保Webpack构建时生成manifest文件，配置示例：
const ManifestPlugin = require('webpack-manifest-plugin');
plugins: [new ManifestPlugin({ fileName: 'manifest.json', publicPath: '/build/' })]
第三步：模板中统一调用= asset('js/app.js') ?>，无需关心哈希是否存在。
这一步漏掉manifest插件，后续所有PHP路径拼接都只是徒劳。
