企业官网建设流程全解析

• 后端
• Web框架

本篇指南面向希望向 Yii 2 框架贡献代码的开发者，完整梳理了 Yii 官方维护的 Git 协作流程：如何 fork 并搭建本地开发环境、如何配置测试与静态分析工具、如何针对 bug 修复与功能增强创建独立分支、规范地更新 CHANGELOG 并最终提交 Pull Request。读完本文，你将掌握一套可直接照做的 11 步贡献流程，以及php build/build开发辅助命令的完整用法，让代码更快、更顺利地被 Yii 核心团队接受。

本文依据仓库中的 docs/internals-ru/git-workflow.md（其英文原版为 docs/internals/git-workflow.md）整理扩充，并结合 build 目录 下的实际源码、phpunit.xml.dist、phpstan.dist.neon、tests/data/config.php 等文件佐证说明。如果你对 Git 与 GitHub 尚不熟悉，建议先了解 GitHub 帮助文档、Try Git 教程或 Git 内部数据模型等入门材料，再进入本文。

一、准备你的开发环境

以下步骤用于搭建一套可用于修改 Yii 框架核心代码的本地开发环境。这些步骤只在第一次贡献时需要执行。

1. Fork 仓库并克隆到本地

在 GitHub 上 fork Yii 2 仓库后，将你的 fork 克隆到开发环境中：

git clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git

如果在 Linux 上配置 Git 与 GitHub 时遇到问题，或出现类似 "Permission Denied (publickey)" 的错误，则需要按 GitHub 官方指引完成 SSH 密钥的配置。如果你对 Git 还不熟练，官方推荐的免费《Pro Git》一书是很好的学习资料。

2. 将主仓库添加为名为 "upstream" 的远程仓库

进入克隆下来的目录（通常名为yii2），执行：

git remote add upstream https://github.com/yiisoft/yii2.git

这样你的本地仓库就有两个远程：origin（你的 fork，负责推送）与upstream（官方主仓库，负责同步最新代码）。在后续所有工作流步骤中，保持origin与upstream分工清晰是基础。

3. 准备测试环境

如果你只打算参与翻译或文档工作，以下步骤可以跳过；但如果要修改框架代码，则必须完成。

安装 PHP 依赖：在仓库根目录执行composer install（假设你已经全局安装了 Composer）。

安装 JavaScript 依赖（如涉及 JS 工作）：

npm install

用于安装 JavaScript 测试工具与依赖（假设已安装 Node.js 和 NPM）。从当前仓库的 package.json 可以看到，JS 测试栈包含 mocha、chai、jsdom、sinon、leche 等，测试入口为npm test，另提供npm run lint用于 eslint 检查（作用于 framework/assets 与 tests/js）。注意：JavaScript 测试依赖 jsdom 库，其要求 Node.js 4 或更新版本，官方更推荐 Node.js 6 或 7。

克隆基础应用（basic）模板并建立软链接：

php build/build dev/app basic

这条命令会克隆 basic 应用模板并安装其 composer 依赖。外部第三方包会正常安装到 vendor 目录，但Yii 框架本体并不会复制一份，而是把当前检出的 yii2 仓库通过软链接指到应用的vendor/yiisoft/yii2，从而保证整个开发环境中只存在一份框架代码。如果需要，可对 advanced 应用执行同样的操作：

php build/build dev/app advanced

该命令内部执行的是composer update，因此也可以用它来更新依赖。

注意：默认情况下 build 命令通过 SSH 协议克隆 GitHub 仓库；如需改用 HTTPS，请在 build 命令后追加--useHttp标志。

这一步完成后，你就拥有了一块可以放心实验 Yii 2 的开发场地。

深入源码：build/build与DevController做了什么

php build/build并非外部工具，而是仓库自带的构建脚本（见 build/build）：它开启YII_DEBUG、加载 composer 自动加载器（兼容 yii2 作为根包或 yii2-basic/yii2-advanced 作为根包两种场景）、加载 framework/Yii.php，然后以yii\build\controllers为命名空间启动一个控制台应用。dev/app、dev/ext等子命令由 build/controllers/DevController.php 实现，其关键行为包括：

• 内置basic、advanced、benchmark三个应用的仓库地址映射，以及 apidoc、authclient、bootstrap、redis、mongodb 等二十余个扩展的地址映射；
• dev/app先克隆应用仓库（若目录不存在），清理其vendor/yiisoft下已存在的软链接，执行composer update --prefer-dist，最后通过linkFrameworkAndExtensions()将 framework 目录和extensions/下已安装的扩展以符号链接方式挂进应用的 vendor 目录；
• 提供--useHttp（克隆改用 HTTPS）与--composerNoProgress（composer 追加--no-progress）两个选项；
• 另有dev/all（安装全部应用与扩展）与dev/run <command>（在所有应用与扩展目录中批量执行命令，例如./build/build dev/run git pull）两个辅助动作。

也就是说，php build/build dev/app basic的"链接"行为是有明确源码依据的：它会删除应用 vendor 目录中的实体目录，再以symlink()指向当前开发仓库，保证你改动框架代码后，应用立即生效，无需重新安装。

可选：运行单元测试

在仓库根目录执行phpunit即可运行单元测试。若未全局安装 phpunit，可使用php vendor/bin/phpunit（Windows 下为vendor/bin/phpunit.bat）。仓库根目录的 phpunit.xml.dist 定义了测试套件（覆盖整个tests目录）、yiiunit\ResultPrinter打印器、以及覆盖率统计的范围与排除项。

部分测试需要额外安装并配置数据库。你可以创建tests/data/config.local.php来覆盖 tests/data/config.php 中的默认配置。从该文件源码可见，默认配置了 cubrid、mysql、sqlite、sqlsrv、pgsql、oci 共六种数据库的 DSN、账号与 fixture 脚本，且会在文件末尾自动 include 同目录下的config.local.php以允许覆盖。例如，修改 MySQL 的用户名与密码，只需在config.local.php中写入：

<?php $config['databases']['mysql']['username'] = 'yiitest'; $config['databases']['mysql']['password'] = 'changeme';

你还可以只运行与当前工作相关的测试组。例如只运行验证器与 redis 相关测试：

phpunit --group=validators,redis

用phpunit --list-groups可以查看所有可用的测试分组。

JavaScript 单元测试则在仓库根目录执行：

npm test

可选：静态分析

Yii 2 使用 PHPStan 进行静态分析，启动命令为：

php vendor/bin/phpstan

Windows 下为vendor\bin\phpstan.bat。默认情况下，PHPStan 使用仓库根目录的 phpstan.dist.neon 作为配置——从该文件可见其分析级别为level: 3，分析路径覆盖build、framework、tests，并排除了tests/data等测试数据目录。你也可以创建自己的phpstan.neon，PHPStan 会优先使用它（仓库中还提供了 phpstan-baseline.neon 与针对 PHP 7.x 的 phpstan-7x.dist.neon、phpstan-baseline-7x.neon 等配套文件）。

关于 PHPDoc 注解的约定：在 PHPDoc 注释中，Yii 使用 PHPStan 类型；如果需要为 Psalm 指定不同的类型（通常在泛型场景下会发生），则应让 Psalm 注解与 PHPStan 注解并存。正确的写法示例如下：

/** * @return Action<covariant static>|null * @phpstan-return Action<covariant static>|null * @psalm-return Action<self>|null */ public function createAction($id) { ... }

即同一处返回值分别用@return（供通用阅读）、@phpstan-return（供 PHPStan 推断）与@psalm-return（供 Psalm 推断）三条注解表达，保证两个分析器都能得到精确的类型信息。

扩展开发

要开发某个扩展，需要先克隆对应扩展的仓库。仓库提供了一条专用命令：

php build/build dev/ext <extension-name> <fork>

其中<extension-name>是扩展名，例如redis；<fork>是你的扩展 fork 地址，例如git@github.com:my_nickname/yii2-redis.git。如果你是框架核心贡献者，可以省略<fork>参数（此时会使用 DevController.php 内置的官方扩展地址，如git@github.com:yiisoft/yii2-redis.git）。

如果想把某个扩展放进应用模板中测试，只需像平时一样把它加入应用的composer.json，例如在 basic 应用的require段添加：

"yiisoft/yii2-redis": "~2.0.0"

然后重新运行php build/build dev/app basic，它会安装该扩展及其依赖，并为extensions/redis创建符号链接——这样你直接工作在 yii2 仓库目录内，而不是 composer 的 vendor 目录里，改动即时生效。

注意：默认通过 SSH 克隆 GitHub 仓库，如需 HTTPS，同样追加--useHttp标志。

二、修复 bug 与开发新功能的完整流程

环境就绪后，就可以开始正式的贡献流程了。下面的 11 个步骤是 Yii 官方推荐的协作规范，请逐步遵循。

1. 确认存在对应的 issue

所有新功能与 bug 修复都应关联一个 issue，作为讨论与文档记录的唯一参照点。动手前花几分钟在 issue 列表中检索是否有匹配项：

• 若已存在对应 issue，请在该 issue 下留言说明你打算接手；
• 若没有匹配的 issue，请新建一个 issue（参见 docs/internals-ru/report-an-issue.md）；如果只是直截了当的小修复，也可以直接创建 Pull Request。

对于小改动、文档问题或简单修复，无需先建 issue，直接提交 Pull Request 即可。

2. 拉取主仓库的最新代码

git pull upstream master

每次开始新贡献，都应从这一步做起，确保你在最新代码上工作。

3. 基于最新 master 创建新的特性分支

这一步非常重要：如果你直接在 master 上开发，你将无法从自己的账号提交第二个 Pull Request。

每个独立的 bug 修复或改动都应有自己的分支。分支名应具备描述性，并以所关联 issue 的编号开头；如果没有关联特定 issue，可省略编号。例如：

git checkout upstream/master git checkout -b 999-name-of-your-branch-goes-here

4. 写代码，做你的"魔法"

确保代码可以工作。单元测试永远受欢迎：经过测试、覆盖率良好的代码能极大简化审查工作；即使只是"描述问题"的失败测试，也同样被接受。

5. 更新 CHANGELOG

编辑 CHANGELOG 文件，把改动记录插入到文件顶部第一个标题（即当前正在开发的版本）之下。从 framework/CHANGELOG.md 可以看到实际格式——当前版本标题为2.0.56 under development，其下每条记录形如：

Bug #999: a description of the bug fix (Your Name) Enh #999: a description of the enhancement (Your Name)

其中#999是Bug或Enh所对应的 issue 编号。变更记录应按类型（Bug、Enh）分组，并按 issue 编号排序。对于非常小的修复（例如拼写错误、文档改动），无需更新 CHANGELOG。

6. 提交你的更改

先把要提交的文件加入暂存区：

git add path/to/my/file.php

也可以使用-p选项交互式挑选要进入本次提交的改动。

然后用描述性的提交信息提交。信息中务必包含#XXX编号，这样 GitHub 会自动把该提交与对应 issue 关联：

git commit -m "A brief description of this change which fixes #999 goes here"

7. 再次拉取 upstream 最新代码到你的分支

git pull upstream master

这确保在提交 Pull Request 之前，你的分支包含最新代码。如果出现合并冲突，请立即解决并再次提交。这样可以保证 Yii 团队能以"一键合并"的方式合入你的改动。

8. 解决冲突后，推送代码到 GitHub

git push -u origin 999-name-of-your-branch-goes-here

-u参数会把本地分支与 GitHub 上的分支建立关联，之后再次执行git push时 Git 会自动知道推送目标。如果你想后续继续向该 Pull Request 追加提交，这会非常方便。

9. 向 upstream 发起 Pull Request

在 GitHub 上进入你的仓库，点击 "Pull Request"，在右侧选择你的分支，并在评论框中填写更多信息。要关联 issue，请在 Pull Request 描述中任意位置写上#999（999 为 issue 编号）。

注意：每个 Pull Request 只应修复单一改动。对于多个互不相关的改动，请分别发起多个 Pull Request。

10. 等待代码评审

会有人评审你的代码，并可能要求你做出修改——此时回到第 6 步即可（只要当前 Pull Request 仍处于打开状态，就无需新开一个）。如果代码被接受，它会被合并进主分支，成为下一个 Yii 版本的一部分；如果未被接受，也不必气馁——不同的人需要不同的功能，Yii 无法满足所有人的全部需求，你的代码仍会留在 GitHub 上，作为有需要的人的参考。

11. 清理

代码被接受或拒绝之后，可以删除本地仓库与origin上工作过的分支：

git checkout master git branch -D 999-name-of-your-branch-goes-here git push origin --delete 999-name-of-your-branch-goes-here

三、关于 CI 的注意事项

为了尽早发现回归，每次对 Yii 代码库的合并都会被 CI 系统捕获并自动运行测试。核心团队不希望过度消耗这一服务，因此在以下情形中，会在合并描述中加入[ci skip]标记，以跳过测试运行：

• 改动只涉及 JavaScript、CSS 或图片文件；
• 仅更新文档；
• 改动只涉及固定字符串（例如翻译更新）。

这些改动本质上不涉及单元测试覆盖的范围，跳过 CI 可以节省构建资源。在当前仓库中，可以结合根目录的 Dockerfile、tests 目录 的测试配置（如 phpunit.xml.dist、tests/bootstrap.php）理解测试运行的整体依赖。

四、命令速查（面向进阶贡献者）

将上述完整流程浓缩为命令序列：

git clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git git remote add upstream https://github.com/yiisoft/yii2.git

git fetch upstream git checkout upstream/master git checkout -b 999-name-of-your-branch-goes-here /* 写代码，如有需要更新 CHANGELOG */ git add path/to/my/file.php git commit -m "A brief description of this change which fixes #999 goes here" git pull upstream master git push -u origin 999-name-of-your-branch-goes-here

再配合环境搭建阶段的composer install、npm install、php build/build dev/app basic（以及需要时对 advanced 应用的同样操作）、phpunit与php vendor/bin/phpstan，你就拥有了一套从搭建、开发、测试、静态分析到提交的完整 Yii 2 贡献闭环。

五、小结

Yii 2 的贡献流程之所以强调"每改动一个独立分支""分支名以 issue 编号开头""CHANGELOG 分组按编号排序""提交信息携带 #XXX"，本质上是为分布式协作中的讨论、追溯与自动关联提供统一的锚点。这套规范配合仓库自带的build工具链（软链接式开发环境）与 PHPStan/phpunit 质量门槛，让外部贡献者与核心团队之间能够高效、可预期地协作。按照本文的步骤走完一遍，你的第一个 Yii 2 Pull Request 就已经在路上了。

• 后端
• Web框架