PHP项目版本归档如何留存历史全量代码包

wen PHP项目 2026-06-25 33

本文目录导读：

方案一：使用 Git 标签 + 手动打包（最基础、最常用）
方案二：通过 Git 服务器 Web 界面下载（团队协作推荐）
方案三：使用自动化 CI/CD 流水线（专业项目推荐）
方案四：手动复制文件夹（不推荐，但临时可用）
关键建议：是否包含 vendor 目录？
最佳实践

在 PHP 项目中，留存历史全量代码包的版本归档，最推荐、最标准的方式是使用 Git（或其他版本控制系统）的标签（Tag）功能，并结合自动化的构建与归档流程。

以下提供几种从简单到专业的方案,供你根据项目规模和团队情况选择。

使用 Git 标签 + 手动打包（最基础、最常用）

这是最简单、最可靠的方法，核心是利用 Git 标签标记版本，在需要时随时导出全量代码。

创建版本标签（Tag）

当你完成一个版本（v1.0.0）的开发并测试通过后，在 Git 中打一个标签：

# 给当前代码打一个轻量级标签
git tag v1.0.0
# 更推荐：打一个附注标签（包含作者、时间、说明信息）
git tag -a v1.0.0 -m "Release version 1.0.0: 修复了XXBug，新增了XX功能"

推送标签到远程仓库

git push origin v1.0.0   # 推送单个标签
git push origin --tags   # 推送所有本地未推送的标签

基于标签导出全量代码（留存/备份）

当需要某个历史版本的全量代码包时：

# 将标签对应的代码导出到 /tmp/v1.0.0 目录（不带 .git 历史）
git archive --format=zip --output=/backup/project-v1.0.0.zip v1.0.0
# 或者导出为 tar.gz
git archive --format=tar.gz --output=/backup/project-v1.0.0.tar.gz v1.0.0

优点：简单、纯净，只包含源代码，不含 .git 目录。

通过 Git 服务器 Web 界面下载（团队协作推荐）

大多数代码托管平台（GitHub, GitLab, Gitee等）都支持直接从标签下载归档文件，这相当于将“留存”职责外包给了平台。

步骤：
1. 在 Git 仓库主页，找到 Releases 或 Tags 页面。
2. 点击某个版本标签旁边的 Download ZIP / Download tar.gz 按钮。
3. 下载即得到该版本的全量代码包。

优点：无需手动打包，平台自动提供，适合团队共享和对外交付。

使用自动化 CI/CD 流水线（专业项目推荐）

对于较大或频繁发版的项目,结合 CI/CD（如 Jenkins, GitLab CI, GitHub Actions）可以实现发版即归档，每次打标签发布版本时，自动生成并保存全量代码包到固定的文件服务器（如 NAS, Amazon S3, 阿里云OSS）。

示例流程（GitLab CI）：

打标签触发流水线：当你 git push --tags 时，CI 自动运行。

构建归档文件：在 .gitlab-ci.yml 中定义任务：

archive:
  stage: build
  script:
    - git archive --format=zip --output=project-${CI_COMMIT_TAG}.zip $CI_COMMIT_TAG
    # 可以将包上传到文件服务器或云存储
    - curl -T project-${CI_COMMIT_TAG}.zip https://your-storage-server/archives/
  only:
    - tags

归档存储：CI 执行完毕后，全量代码包自动存到了指定位置，并与 Git 标签一一对应。

优点：自动化、不可篡改（CI 日志可追溯）、支持大规模项目。

手动复制文件夹（不推荐，但临时可用）

如果完全没有用 Git，只能手动留存：

在发版时,将整个项目文件夹（包括 vendor 依赖包）复制一份。
重命名为 project_YYYYMMDD_v1.0.0。

用 tar/zip 打包：

tar -czf project_20231027_v1.0.0.tar.gz project_YYYYMMDD_v1.0.0/

严重缺点：

容易漏文件：特别是 .env、vendor、node_modules 等隐藏或系统无关文件。
版本比对困难：无法快速看出两个版本的差异。
存储膨胀：每次都是近似全量复制。

关键建议：是否包含 `vendor` 目录？

PHP 项目中 vendor 目录（Composer 依赖）是否应包含在历史全量代码包中？这取决于你的环境保障能力：

做法	说明	场景
不包含（推荐）	只归档 `src/`、`config/`、`composer.json`、`composer.lock` 等，部署时通过 `composer install` 基于 `composer.lock` 恢复精确依赖。	如果你能确保未来也能访问同版本的 Composer 包源（官方 Packagist 一般可以）。
包含	留存时连带 `vendor` 一起打包，确保完全“离线可用”。	隔离网络环境（内网、专有云）、或项目依赖的私有包可能无法永久访问。