laravel ci/cd核心卡点是环境一致性、php与node.js协同构建及构建产物安全交付。npm ci必须替代npm install以确保lock文件校验；npx mix --production优于npm run production；前后端须分job构建并显式传递artifacts；mix-manifest.json必须随静态资源原子发布，否则导致白屏。
Laravel 项目的 CI/CD 流水线不是“配个 .gitlab-ci.yml 就能跑通”，核心卡点在环境一致性、PHP 与 Node.js 协同构建、以及构建产物如何安全交付到运行环境——三者缺一不可。
为什么 npm ci 必须替代 npm install 在 CI 中
本地开发用 npm install 没问题，但 CI 环境里它会忽略 package-lock.json 的完整性校验，导致不同机器装出不同版本的依赖（比如 laravel-mix@6.0.49 和 @6.0.51 可能产出不同哈希的 CSS 文件）。npm ci 强制按 lock 文件安装，且跳过 devDependencies 的解析开销，构建更稳定、更快。
- 必须在 CI 脚本开头执行：
npm ci --no-audit --prefer-offline - 若项目含私有 npm 包，需提前配置
NPM_TOKEN并在 CI 中注入.npmrc - GitLab CI 中注意缓存
node_modules/路径，但每次npm ci前要清空，避免 lock 文件变更被忽略
npx mix --production 和 npm run production 的实际差异
两者最终都调用 Webpack 打包，但触发路径不同：npm run production 是从 package.json 的 scripts 启动，依赖 cross-env 设置 NODE_ENV=production；而 npx mix --production 直接调用 Mix CLI，内置环境判断，不依赖脚本定义。CI 中推荐后者——减少一层 shell 解析，避免因 cross-env 版本或平台差异（如 Windows vs Linux runner）导致环境变量未生效。
-
npx mix --production会自动启用version()、压缩 JS/CSS、移除 source map - 若自定义了
webpack.mix.js中的mix.setPublicPath()，CI 中必须确保输出路径与 Laravel 的public/目录一致，否则mix-manifest.json写入位置错位 - 构建失败时常见报错：
Error: Cannot find module 'laravel-mix'——说明node_modules未正确安装或npx未找到全局 bin
PHP 构建与前端构建必须分阶段，不能混在同一 job
Node.js 构建耗内存、时间长，PHP 测试和 composer install 依赖扩展（如 mbstring），二者环境需求冲突。合并在一个 job 容易超时、OOM 或扩展缺失。GitLab CI 或 GitHub Actions 都应拆成至少两个 job：一个是 frontend-build（Node 16+，输出 public/js 和 mix-manifest.json），另一个是 php-test-deploy（PHP 8.1+，装扩展，跑 PHPUnit，最后把前端产物复制进来）。
- 前端 job 的产物必须显式声明为
artifacts（如 GitLab 的artifacts.paths或 GitHub 的upload-artifact） - PHP job 需用
download-artifact（GitHub）或needs+dependencies（GitLab）拉取前端产物，再合并进部署包 - 切忌在 PHP job 里重新跑
npx mix—— 既浪费资源，又可能因 Node 版本不一致导致哈希值变化，破坏长期缓存
mix-manifest.json 如何影响线上缓存与回滚
这个文件是 Laravel Mix 缓存策略的唯一事实来源。Laravel 的 Mix::get() 辅助函数靠它重写 HTML 中的资源路径（如 /js/app.js → /js/app.js?id=abc123）。如果 CI 构建后没把它一起发布，或者部署时覆盖错了位置（比如写到了 storage/ 下），页面就会 404。
-
mix-manifest.json必须和public/js/、public/css/在同一发布包中，且权限为 644 - 蓝绿部署时，新旧版本的
mix-manifest.json不可共存于同一目录；建议用符号链接切换current → release-20260514，确保原子性 - 回滚时，仅还原 PHP 代码不够——必须同步还原对应版本的
mix-manifest.json和静态资源，否则页面加载旧 JS 但引用新哈希路径，白屏
真正难的不是写对第一版流水线，而是当团队开始并行开发多个分支、引入 SSR 或微前端时，mix-manifest.json 的生成时机、多环境变量隔离、以及构建产物跨 stage 传递的可靠性，会突然变成高频故障点。
