EverShop 贡献指南：从本地开发环境搭建到提交 Pull Request 的完整工作流
EverShop 贡献指南：从本地开发环境搭建到提交 Pull Request 的完整工作流
EverShop 是一个基于 TypeScript、React 与 Postgres 构建的开源电商平台。无论你是想修复 Bug、讨论代码现状、提出新功能，还是改进文档，CONTRIBUTING.md 都为你定义了一条清晰、可执行的贡献路径。本文将围绕这份贡献指南展开，结合仓库内的脚本配置与源码实现，完整讲解本地开发环境的搭建步骤、数据库初始化、构建与测试流程、Pull Request 提交流程，以及高质量 Bug 报告的撰写标准，帮助你从"想贡献"到"能贡献"一步到位。
一、你能以哪些方式参与贡献
EverShop 欢迎任何形式的输入，贡献方式主要包括四类：
- Reporting a bug（报告 Bug）：发现错误信息或运行问题时，通过 GitHub Issues 提交问题；
- Discussing the current state of the code（讨论代码现状）：参与代码层面的讨论，帮助澄清设计意图；
- Submitting a fix（提交修复）：针对已知问题提交代码修复；
- Proposing new features（提议新功能）：提出新的能力或改进建议。
在开始任何贡献之前，请先阅读仓库根目录下的 CODE_OF_CONDUCT.md（行为准则），确保所有互动与提交都遵循社区规范。
提示：仓库采用 npm workspaces 管理多个子包（见 package.json 中的
workspaces: ["packages/*", "extensions/*"]），核心源码位于packages/evershop，因此贡献代码时大多会改动该目录下的src文件。
二、本地开发环境搭建：Fork、Clone 与分支管理
贡献代码的第一步是在本地复刻并运行这个项目，官方推荐的流程如下。
1. Fork 并克隆仓库
先在 GitHub 上 Fork 本仓库到自己的账号，然后将它克隆到本地设备：
git clone https://github.com/evershopcommerce/evershop.git
2. 创建新的功能分支
克隆完成后，为你的改动创建一个独立分支，避免直接在主分支上工作：
git checkout -b MY_BRANCH_NAME
3. 安装依赖
在仓库根目录执行依赖安装（workspaces 会一次性安装 packages/* 与 extensions/* 下所有子包的依赖）：
npm install
三、创建 Postgres 数据库并初始化 Schema
1. EverShop 使用 Postgres 作为数据库存储
EverShop 的数据存储完全依赖 Postgres（核心连接实现见 packages/evershop/src/lib/postgres/connection.ts，查询构建器位于 packages/postgres-query-builder）。如果你本机没有现成的 Postgres 服务，可以直接使用仓库提供的 docker-compose.yml 快速拉起一个 Postgres 16 实例：
database:
image: postgres:16
restart: unless-stopped
volumes:
- postgres-data:/var/lib/postgresql/data
environment:
POSTGRES_PASSWORD: postgres
POSTGRES_USER: postgres
POSTGRES_DB: postgres
ports:
- "5432:5432"
启动方式：
docker compose up -d database
2. 运行安装命令创建数据库 Schema
npm run setup
根目录 package.json 中该命令的真实定义是 "setup": "evershop install"，即调用 @evershop/evershop 包提供的 CLI（入口见 packages/evershop/src/bin/evershop.js）。CLI 安装器位于 packages/evershop/src/bin/install/index.js，它是一段交互式流程，会依次询问：
- Postgres Database Host（默认
localhost） - Postgres Database Port（默认
5432） - Postgres Database Name（默认
evershop） - Postgres Database User（默认
postgres） - PostgreSQL Database Password（默认空）
回答完这些问题后，安装器会尝试连接数据库，优先走 SSL（ssl: true），若数据库不支持 SSL 则自动降级为 ssl: false；随后创建 .env 文件、建表迁移（调用 migrate 与 getCoreModules），并引导你创建管理员账号。
注意：如果你已经通过环境变量（如
DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PASSWORD）配置了数据库，安装器会直接跳过交互询问并提示"看起来你已经安装过系统"，此时请改用npm run build+npm run start启动商店。这也是 Docker 部署方式不执行npm run setup的原因——环境变量在docker-compose.yml中直接注入。
四、启动开发服务器与构建
1. 启动开发服务器
npm run dev
对应脚本为 node ./packages/evershop/dist/bin/dev/index.js，开发模式下会启用热更新（webpack-dev-middleware / webpack-hot-middleware 等见 packages/evershop/src/lib/webpack 目录），改动源码后浏览器与页面即时刷新，适合日常迭代调试。
2. 构建生产版本
npm run build
该命令执行 node ./packages/evershop/dist/bin/build/index.js，会完成模块扫描、路由注册、客户端与服务端两套 webpack 构建（相关逻辑见 packages/evershop/src/bin/build 目录）。
3. 测试生产构建产物
npm run start
构建完成后用 start 以生产模式启动，验证构建产物能否正常运行。生产与开发入口分别对应 dist/bin/start/index.js 与 dist/bin/dev/index.js。
补充：根目录还提供了
npm run compile（用 swc 把src编译到dist）、npm run compile:tsc（tsc + 静态资源拷贝）等编译命令，分别用于加速编译与完整类型检查两种场景。
五、运行测试与代码规范检查
1. 运行 Jest 单元测试
npm run test
该命令在根目录 package.json 中定义为：
ALLOW_CONFIG_MUTATIONS=true NODE_OPTIONS=--experimental-vm-modules node_modules/jest/bin/jest.js
结合 jest.config.js 可以看出关键约定：
- 测试环境为
node； - 通过
moduleNameMapper将@evershop/postgres-query-builder、@components/*等内部别名映射到dist构建产物； - 样式文件（
.css/.scss）被替换为 tests/styleStub.cjs 桩模块； - 测试匹配规则为
**/dist/**/tests/**/unit/**/*.test.[jt]s，即单元测试面向 编译后的dist目录 中的tests目录，例如packages/evershop/src/lib/router/tests、packages/evershop/src/lib/middleware/tests等测试源码会先经编译再被 Jest 收集。
仓库内同时存在大量端到端测试（Playwright），通过 npm run test:e2e 运行，配置位于 tests/e2e，覆盖 admin 后台、Page Builder、storefront 等模块。
2. 运行 Lint 检查
npm run lint
对应脚本为 eslint --fix --ext .js,.jsx,.ts,.tsx ./packages，即对 packages 目录下所有 JS/TS 源码执行自动修复式检查。从 eslint.config.js 可以看到项目采用的规范要点：
- 使用
@typescript-eslint/parser与@typescript-eslint/eslint-plugin处理 TS/TSX； - 集成 React 与 jsx-a11y 推荐规则；
- 开启 import 排序规则（
import/order，按 builtin → external → internal → parent → sibling → index 分组并字母排序）； - 将
no-console设为 error，禁止在业务代码中直接输出日志（日志统一走 packages/evershop/src/lib/log/logger.js）； - 忽略
dist、tests、extensions、themes等目录。
提交代码前先跑一遍 lint，能显著减少 PR 评审中的低级问题。
六、提交 Pull Request 与许可协议
1. 向 dev 分支发起 Pull Request
本地完成修改、通过测试与 lint 之后，请向仓库的 dev 分支 提交 Pull Request（不要直接提交到 main 分支）。PR 描述应清晰说明改动了什么、为什么这样改，以及必要的验证结果。
2. 贡献代码的许可约定
你提交的任何代码改动，默认遵循与项目相同的 GNU General Public License v3.0（GPL-3.0）。
也就是说，一旦你提交代码，你的提交内容即被理解为同样采用覆盖该项目的 GPL-3.0 许可（仓库根目录的 LICENSE 文件即为许可原文）。如果你对这一点有顾虑，可以随时联系维护者沟通。
七、如何撰写高质量的 Bug 报告
EverShop 使用 GitHub Issues 追踪公开 Bug，贡献者通过 issues 提交问题。一份优秀的 Bug 报告应当包含以下要素：
1. 摘要与背景
- 你使用的 EverShop 版本（可在根目录 package.json 的
version字段查看，当前仓库版本为2.2.1）； - 你使用的 Node.js 版本；
- 你使用的 操作系统；
- 你使用的 Postgres 版本。
2. 复现步骤
- 尽量具体地列出复现步骤；
- 尽可能附上示例代码，帮助维护者快速定位；
- 明确"复现路径"是从全新安装开始，还是在特定模块/页面上触发。
3. 期望结果与实际结果
- What you expected would happen：描述你预期应该发生的行为；
- What actually happens：描述实际发生的现象（含报错日志、截图等）。
4. 补充说明
- Notes：写下你对问题成因的猜测、已经尝试过但无效的排查手段等，这些信息往往能大幅加速问题定位。
八、贡献前的最终检查清单
结合 CONTRIBUTING.md 与仓库脚本，提交 PR 前建议逐项确认：
| 检查项 | 对应命令/文件 |
|---|---|
| 依赖已安装 | npm install |
| 数据库已初始化 | npm run setup（交互式，见 install/index.js） |
| 开发服务器可启动 | npm run dev |
| 生产构建通过 | npm run build |
| 生产产物可运行 | npm run start |
| 单元测试通过 | npm run test（配置见 jest.config.js） |
| Lint 检查通过 | npm run lint（配置见 eslint.config.js） |
| 分支策略正确 | 新分支开发，PR 提交到 dev 分支 |
| 许可确认 | 贡献默认遵循 GPL-3.0 |
完成以上流程后，你的贡献就进入维护者评审环节。EverShop 的开源协作正是建立在"透明开发流程 + 明确贡献规范"之上——按照这份指南操作，无论是首个 Bug 修复还是新功能提案，都能以最高效的方式被社区接收与处理。