给 Bagisto 提交代码前漏掉这 3 步，CI 大概率红

【免费下载链接】bagistoOpen Source eCommerce & Multi-Vendor Marketplace Platform Built with Laravel for Enterprise-Scale Commerce, Supporting 10M+ SKUs项目地址: https://gitcode.com/gh_mirrors/ba/bagisto

给 Bagisto 提交代码，翻车几乎都发生在评审开始之前：你照着 issue 写了两天的功能，第二天打开仓库，发现另一个人已经在同一个 issue 下留言并被指派，你的 Pull Request 成了第二份，整晚白干；或者你信心满满提了 PR，CI 却在你从没跑过的翻译检查上亮红——一个 key 只写进了 en，剩下 22 个语言包全部缺位。下面这套流程，就是帮你在本地提前拦住这些坑。

一张表看清：改什么、提哪里、跑什么

Bagisto 当前有两条活跃分支：2.4是正在维护的发布线，master是下一条发布线。更早的1.x、2.1到2.3一律不再接收新改动，别再往那里提了。提哪条、跑哪些检查，照这张表走就行：

规则只有一条：从哪条线切分支，PR 就提回哪条线，别跨线混提。

认领、对齐、切分支：动手前的三件事

⚠️ 1.先在 issue 下留言认领。一句简短的"我想接这个"就够了，然后等被 assign。很多人会同时看上同一个 issue，重复劳动往往要等第二份 PR 到达才被发现——认领这一步，就是替别人省一个晚上。已被认领但很久没动静的，回原帖问进展，别开竞争性 PR。

2. 方向先在 issue 里对齐。新功能尤其如此：先讨论方案，最好能给出一个展示解决思路形态的最小实现，别抛一个空想法。带着"惊喜"到达的 PR，被拒的概率远高于方向明确但实现粗糙的 PR——拒绝理由通常是方向，而不是代码质量。

3. 从目标分支切出工作分支，命名跟 issue 走，比如issue-1234。仓库里没有development分支，也别找。

写代码时随手对照：一半交给工具，一半靠人眼

机器能查的和人眼要核的，放在脑子里分成两组。

机器能查的：Pint 两个命令差在哪

代码风格由 Laravel Pint 管，pint.json 里就一行预设：{"preset": "laravel"}。开 PR 前跑一次检查命令，它会只报告、不改写文件，返回非零退出码就说明有风格问题，CI 执行的正是这一条：

vendor/bin/pint # 自动修复，直接改写文件 vendor/bin/pint --test # 只检查不修改，CI 同款

本地先用不带--test的那条把文件修干净，再用--test确认一遍。另外注意 Pint 不管.blade.php，Blade 模板的格式只能手工把握——这里有个坑：你改到的 Blade 文件里即使有历史风格问题，评审时也会算在你头上。

人眼要核的：评审者会逐条过目的规则

这几条没有任何工具帮你兜底，每条对应一句"为什么"：

1. 每个方法、属性、常量都带 docblock，不管 public 还是 private——评审靠注释定位意图；
2. 类成员按固定顺序：常量 → 属性 → 构造函数 → public → protected → private——扫读结构时不用跳；
3. 方法体内禁止注释，PHP、Blade、JS、Vue 一视同仁——需要解释的代码，抽一个命名方法，让名字自解释；
4. 数据库访问一律走 repository，唯一例外是 DataGrid 的prepareQueryBuilder()——各包的Repositories/目录就是这条规则的落点，比如 packages/Webkul/Core/src/Repositories；
5. 所有面向用户的字符串必须走trans()，且 key 要同步进全部 23 个语言目录（en 加另外 22 个），缺一个 CI 就红。

PHPDoc 还有个小格式容易被挑：@param与类型之间、类型与变量名之间各留两个空格——@param string|array $loader。原则是类型信息能写进函数签名就写签名，@param/@return只补充原生类型说不出的东西，比如数组的形状。

编译产物别提交：在包目录里构建

Bagisto 的前端源码和构建产物有明确分界：源码放在各包的src/Resources/assets/下，产物输出到public/themes/*/*/build/。编译后的 bundle 又大又没法评审，还是夹带恶意代码的现成通道，所以由维护者统一生成提交，你不该碰它。

⚠️ 构建必须进你改动的包里执行，从仓库根目录跑是无效的——Admin、Shop、Installer 各自维护独立的package.json与 vite.config.js。以 Admin 为例，前端源码就分css/、js/、locales/等子目录，构建完是这样一套完整主题：

这一步只在前端有变更时才需要跑：

cd packages/Webkul/Admin && npm install && npm run build # 换成 Shop 或 Installer 同理

从本地到 CI：提 PR 前的三级检查流

第一级：本地三条命令，拦住 90% 的红灯

第一条防风格检查打脸，第二条防"你机器上好的"，第三条防翻译漏项。动了任何trans()的 key 就必须跑第三条，它以 en 为基准逐语言比对文件夹、文件、key 和结构：

vendor/bin/pint --test # 风格，CI 同款命令 vendor/bin/pest # 单元与功能测试，Pest 是主测试栈 php artisan bagisto:translations:check # 23 个语言包一致性

最后一条的实现在 packages/Webkul/Core/src/Console/Commands/TranslationsChecker.php，支持--locale、--package收窄范围，--details给出带行号的 key 差异；退出码非零即代表没同步好。

第二级：包内跑 Playwright，拦住 UI 流程问题

单元测不到的东西——页面跳转、表单提交——靠端到端测试兜底。它按包运行，进包目录执行：

cd packages/Webkul/Admin && npx playwright test --config=tests/e2e-pw/playwright.config.ts

playwright.config.ts 里是串行执行（workers: 1）、60 秒用例超时，失败时自动留存整页截图、视频和 trace，baseURL取自.env的APP_URL——也就是说，你得先有一个能访问的本地 Bagisto 实例。

第三级：CI 标签触发，按需跑浏览器测试

CI 里 Playwright 不默认全量跑，太贵。PR 打上Need Playwright Testing标签后才会触发，标签在，之后每次 push 都会再跑一遍。本地能跑包内 E2E 就先跑，跑不动也别裸奔，至少在 PR 描述里把"跑了哪些检查、跳过了哪些、为什么"如实写清——评审者靠这段话决定从哪看起。

最容易翻车的五个细节

❌ 把public/themes/*/build/里的编译产物一起提交 ✅ 只提交src/Resources/assets/下的源码，产物留给维护者生成

❌ 新文案只写进了 en 语言包，觉得英文是"母版"就行 ✅ key 同步进全部 23 个语言目录，本地先跑bagisto:translations:check验证

❌ 在仓库根目录直接npm run build✅cd packages/Webkul/<包名>再构建，各包各自维护构建配置

❌ 只跑了vendor/bin/pest就提 PR，风格问题留给 CI 发现 ✅ 先vendor/bin/pint修文件，再vendor/bin/pint --test确认，和 CI 对齐

❌ PHPDoc 随手写@param string $loader✅ 类型两侧各留两空格@param string $loader，类型优先写进函数签名

把整条动线压成一屏

一句话版本：认领 issue 等指派 → 按改动类型从对应发布线切分支 → 前端改动在包内构建、不提交产物 → 提交前过 Pint、Pest 和翻译检查 → 必要时跑包内 Playwright 并贴好 CI 标签 → PR 描述如实交代检查范围。

📌 直接复制收藏：

# 0. issue 下留言认领，等 assign；新功能先对齐方案 # 1. 从目标分支切工作分支：bug 修复/小改进 → 2.4，新特性 → master git checkout 2.4 && git checkout -b issue-1234 # 2. 前端有改动时，进包构建（跳过产物提交） cd packages/Webkul/Admin && npm install && npm run build # 3. 本地三项验证 vendor/bin/pint --test vendor/bin/pest php artisan bagisto:translations:check # 改过 trans() key 才需要 # 4. 涉及 UI 流程：包内跑端到端 cd packages/Webkul/Admin && npx playwright test --config=tests/e2e-pw/playwright.config.ts # 5. 给 PR 打 Need Playwright Testing 标签，描述里写清跑过/跳过的检查

【免费下载链接】bagistoOpen Source eCommerce & Multi-Vendor Marketplace Platform Built with Laravel for Enterprise-Scale Commerce, Supporting 10M+ SKUs项目地址: https://gitcode.com/gh_mirrors/ba/bagisto