真正原因是路径错位：post-install-cmd 在项目根目录执行，但 yarn 命令仅在 frontend/ 等子目录下有效，导致找不到 yarn 或 vite；ci 环境未全局安装 yarn 时更易失败。
composer install 后自动执行 yarn build 可能失败的真正原因
不是脚本没写对，而是 post-install-cmd 中的命令默认在项目根目录执行，但 yarn 命令却在 frontend/ 或 resources/ 目录下才有意义。路径错位会导致 yarn: command not found 或 Cannot find module 'vite'。
常见错误现象：
- 本地运行正常，CI 构建失败——因为 CI 环境没装全局
yarn，只依赖node_modules/.bin/yarn -
yarn install成功，yarn run build报错找不到vite——实际是package.json在子目录，但命令没cd进去 - Windows 上
cd frontend && yarn build失败——&&在 cmd.exe 下不生效，PowerShell 或 Git Bash 才支持
实操建议：
- 统一用
node_modules/.bin/yarn调用，避免依赖全局安装："./frontend/node_modules/.bin/yarn install --frozen-lockfile" - 改用封装脚本（如
scripts/build-frontend.sh），开头加#!/usr/bin/env bash并设为可执行，再在composer.json里调用"bash scripts/build-frontend.sh" - CI 环境务必先
npm install -g corepack，再corepack enable，确保yarn版本与.yarnrc.yml一致
为什么 production 环境不能只靠 --no-dev 就完事
composer install --no-dev 只跳过 require-dev 包，但它完全不管 vendor/ 是否和 composer.lock 对得上。线上跑崩的典型场景：有人手动删过 vendor/monolog/monolog，或者 CI 之前跑过 composer update 没提交新 lock 文件，此时 --no-dev 会直接复用残缺的 vendor/，直到某个 new Logger() 报 Class not found。
实操建议：
- 生产部署必须三步走：
rm -rf vendor/→git checkout -- composer.lock（确保和开发环境一致）→composer install --no-dev --optimize-autoloader --no-interaction - CI 脚本里禁用
composer update，所有依赖变更必须由开发者本地composer update --lock后提交新composer.lock - 验证是否真同步：部署后运行
composer show monolog/monolog，版本号必须和composer.lock里记录的完全一致（含小版本）
config.platform 写了却没生效？检查这三个硬性条件
config.platform 是控制多环境 PHP 版本兼容性的关键开关，但 90% 的失效是因为格式或位置错。它不是“写了就管用”的配置项。
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
必须同时满足：
- 必须放在
composer.json根级config对象下，不能嵌套在extra或scripts里，键名严格为"platform" - PHP 版本号必须写死到小版本，例如
"php": "8.1.10"；写"8.1"、"^8.1"或"8.1.0"（末尾缺零）全都不生效 - 改完后必须删掉
vendor/和composer.lock，再重新composer install——旧 lock 文件会沿用历史解析结果，不会自动刷新平台约束
验证方式：composer install --dry-run 日志里出现 Platform configuration: php 8.1.10 才算真正起效；否则 composer show php 输出仍是系统当前版本。
前端构建产物该放哪？别让 public/ 变成垃圾场
很多人把 yarn build 输出直接扔进 public/，结果 public/js/app.js 和 public/css/app.css 混着 public/index.php，Git 提交时容易漏掉新版文件，上线后缓存又清不干净。
推荐做法：
- 前端构建输出统一到
public/build/（Laravel/Vue 默认）或web/assets/（Symfony 习惯），并在.gitignore明确忽略该目录 - PHP 模板里引用资源时用动态路径：
<script src="%7B%7B%20asset('build/app.js')%20%7D%7D"></script>，而不是硬编码/js/app.js - 构建命令必须带哈希（如 Vite 的
build.rollupOptions.output.entryFileNames设为[name].[hash].js），避免 CDN 缓存旧文件
最容易被忽略的是：构建产物目录必须在 composer.json 的 autoload.files 或 autoload.classmap 之外——它不是 PHP 类，不该被 Composer 自动加载扫描，否则 composer dump-autoload 会报错或变慢。
