> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 包的版本兼容性管理

> 从 composer.json 更新到 GitHub Actions 测试矩阵配置，实用地讲解应对 Laravel 与 PHP 主版本升级的包维护策略。

Laravel 每年 2〜3 月发布主版本。对包开发者来说，尽快完成对新版本的适配既是对生态的贡献，也是提升自身包信誉的重要活动。

<Info>
  本页是[包开发基础](/zh/advanced/package-development)的姊妹页面。前提是你已经掌握包开发的基础知识（Service Provider、`composer.json` 结构等）。
</Info>

## 应对 Laravel 主版本升级

### 应对流程

<Steps>
  <Step title="更新 composer.json 的 require">
    向依赖范围中添加新版本。若要继续支持旧版本，用 `||` 并列。

    ```json theme={null}
    "require": {
        "php": "^8.2",
        "illuminate/support": "^12.0||^13.0"
    }
    ```

    新版本适配完成、结束旧版本支持时删除旧约束。

    ```json theme={null}
    "require": {
        "php": "^8.3",
        "illuminate/support": "^13.0||^14.0"
    }
    ```

    <Tip>
      依赖 `illuminate/support` 而非整个 `illuminate/framework`，可以保持依赖树精简。
    </Tip>
  </Step>

  <Step title="用新版本运行测试">
    在本地或 CI 环境使用新的 Laravel 版本运行测试。

    ```shell theme={null}
    composer update
    vendor/bin/pest
    ```

    通过即可基本确认兼容性。未通过时需要针对变更或删除的 API 进行修改。
  </Step>

  <Step title="向 GitHub Actions 测试矩阵添加新版本">
    在 CI 测试矩阵中加入 Laravel 新版本，持续验证兼容性。详见[测试矩阵配置示例](#测试矩阵配置示例)。
  </Step>

  <Step title="发布新版本适配">
    将包含 `composer.json` 变更的新版本打标签并发布。用户只需 `composer update` 就能在新的 Laravel 版本上安装。
  </Step>
</Steps>

### 参考官方包

对适配方式犹豫时，参考 Laravel 官方包的 `composer.json` 最为稳妥。

* [laravel/socialite](https://github.com/laravel/socialite)
* [laravel/horizon](https://github.com/laravel/horizon)
* [laravel/telescope](https://github.com/laravel/telescope)

这些包由 Laravel 团队维护，是最早适配新版本的实例，`illuminate/*` 依赖版本的写法也很有参考价值。

## PHP 版本要求的更新

Laravel 升级有时会提高 PHP 最低要求。请一并在包的 `composer.json` 中更新 PHP 要求。

| Laravel    | 最低 PHP 版本 |
| ---------- | --------- |
| Laravel 11 | PHP 8.2   |
| Laravel 12 | PHP 8.2   |
| Laravel 13 | PHP 8.3   |
| Laravel 14 | PHP 8.4   |

```json theme={null}
"require": {
    "php": "^8.2",
    "illuminate/support": "^11.0||^12.0||^13.0"
}
```

### 积极使用新 PHP 特性时

若要使用 PHP 8.3 之后的特性（类型化常量、新的随机函数等），需要判断是否要提高最低要求。从 SemVer 角度看提高最低要求属于破坏性变更，因此建议在主版本升级时进行。

```json theme={null}
"require": {
    "php": "^8.3",
    "illuminate/support": "^12.0||^13.0"
}
```

<Warning>
  提高 PHP 最低要求后，使用旧 PHP 的用户就无法升级你的包。请务必在 README 与 CHANGELOG 中明确注明并事先通知。
</Warning>

## 结束旧版本支持的策略

一直维护旧版本从长远看会拉高维护成本。制定明确的支持策略并定期结束旧版本支持，是包健康运营的重要一步。

### 结束支持的时机

常见做法是**与 Laravel 支持期对齐**。Laravel 为每个版本提供 18 个月 Bug 修复与 2 年安全修复。包也采用相同策略会让用户更易理解。

| 判断标准           | 说明                       |
| -------------- | ------------------------ |
| Laravel 官方支持结束 | 与对应 Laravel 版本停止支持同步     |
| 使用情况           | Packagist 下载统计显示旧版本用户变少时 |
| 增加功能的障碍        | 旧版本适配让新功能实现变得复杂时         |

### 在 README 中写明支持策略

为让用户对预期有正确的判断，请在 `README.md` 中记载支持策略。

```markdown theme={null}
## Version Compatibility

| Package | Laravel | PHP  |
|---------|---------|------|
| 3.x     | 13.x    | ^8.2 |
| 2.x     | 11.x, 12.x | ^8.2 |
| 1.x     | 10.x    | ^8.1 |

Only the latest major version receives new features.
Security fixes are backported to the previous major version for 12 months.
```

### 维护旧版本的成本

持续维护旧版本会产生以下成本。

* **重复的 Bug 修复** — 需要在多个分支修复同一 Bug
* **分支代码增加** — 用条件分支处理各版本差异，复杂度上升
* **测试矩阵膨胀** — CI 运行时间变长
* **安全补丁更复杂** — 需要谨慎地向旧版本回移

在整个生态持续升级的背景下，适时结束旧版本支持也能促使用户迁移到最新环境。

## 早期适配的优势

在 Laravel 发布同时完成适配，用户可以立刻迁移到新版本。这是包信誉的重要信号。

### 用开发版预先验证

Laravel 不发布 beta/RC，但可以通过 `dev-master` 或 `@dev` 安装尚在开发中的下一版本。在主版本发布前预先跑通，就能做到零日适配。

```shell theme={null}
# 用 dev-master 安装下一版本
composer require laravel/framework:dev-master --no-update
composer update
vendor/bin/pest
```

也可以通过 `@dev` 约束安装。

```shell theme={null}
composer require laravel/framework:^14.0@dev --no-update
composer update
vendor/bin/pest
```

将 `minimum-stability` 设为 `dev` 可以解析对开发版的依赖。

```json theme={null}
{
    "minimum-stability": "dev",
    "prefer-stable": true
}
```

<Tip>
  指定 `prefer-stable: true` 后，若存在稳定版会优先使用稳定版。既能用开发版测试，又能保证正式发布时自动切回稳定版。
</Tip>

### 第一步只改 composer.json 就够了

在完成完全兼容性确认之前，仅仅更新 `composer.json` 的依赖范围并发布，就能让用户安装到包。

```json theme={null}
"illuminate/support": "^12.0||^13.0"
```

小问题可以在发布后通过 PATCH 版本修复。与其等完美适配，不如优先让包可以被安装。

### 追踪发布信息

以下是及时把握新版本发布信息的手段。

| 信息源                                                                           | 内容                                                             |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
| GitHub Watch 功能                                                               | 通过仓库「Watch → Custom → Releases」接收邮件通知。除 framework 外，也可以订阅其他主要包 |
| [Laravel 官方博客](https://laravel.com/blog)                                      | 主版本发布公告与新特性介绍                                                  |
| [Laravel 官方文档 Upgrade Guide](https://laravel.com/docs/upgrade)                | 破坏性变更清单                                                        |
| [laravel/framework 提交日志](https://github.com/laravel/framework/commits/master) | 想抢先了解下一个版本时可直接看提交日志                                            |

## 测试矩阵配置示例

以下是 GitHub Actions 中对多种 Laravel 与 PHP 版本组合进行自动测试的工作流示例。

```yaml theme={null}
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix:
        php: [8.2, 8.3, 8.4]
        laravel: ["^12.0", "^13.0"]
        include:
          - laravel: "^13.0"
            testbench: "^10.0"
          - laravel: "^12.0"
            testbench: "^9.0"

    name: PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }}

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: dom, curl, libxml, mbstring, zip
          coverage: none

      - name: Install dependencies
        run: |
          composer require "laravel/framework:${{ matrix.laravel }}" \
                           "orchestra/testbench:${{ matrix.testbench }}" \
                           --no-interaction --no-update
          composer update --prefer-dist --no-interaction

      - name: Run tests
        run: vendor/bin/pest
```

### fail-fast: false 的重要性

设置 `fail-fast: false` 后，即便某个组合失败，其他组合的测试仍会继续。可以在一次 CI 中知道所有出问题的组合。

### 逐步更新测试矩阵

Laravel 新版本发布后加入矩阵，结束旧版本支持时再从矩阵移除。

```yaml theme={null}
# 待 Laravel 14 发布后添加
matrix:
  laravel: ["^13.0", "^14.0"]
  include:
    - laravel: "^14.0"
      testbench: "^11.0"
    - laravel: "^13.0"
      testbench: "^10.0"
```

## composer.json 示例

以下是支持多版本的 `composer.json` 完整示例。

```json theme={null}
{
    "name": "acme/courier",
    "description": "A Laravel courier package",
    "type": "library",
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "illuminate/support": "^12.0||^13.0"
    },
    "require-dev": {
        "orchestra/testbench": "^9.0||^10.0",
        "pestphp/pest": "^3.0",
        "pestphp/pest-plugin-laravel": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Courier\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\Courier\\Tests\\": "tests/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Acme\\Courier\\CourierServiceProvider"
            ]
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}
```

## 版本升级应对清单

<AccordionGroup>
  <Accordion title="Laravel 新版本发布前">
    * [ ] 用开发版（`dev-master` / `@dev`）跑通功能
    * [ ] 在官方 Upgrade Guide 中确认破坏性变更
    * [ ] 在测试环境实现新版本适配
    * [ ] 将新版本加入测试矩阵在 CI 中验证
  </Accordion>

  <Accordion title="发布后初期应对">
    * [ ] 在 `composer.json` 的 `illuminate/*` 中加入新版本
    * [ ] 按需更新 PHP 要求
    * [ ] `require-dev` 中的 `orchestra/testbench` 也升级到对应版本
    * [ ] 打新版本标签并同步到 Packagist
    * [ ] 更新 README 中的版本兼容表
  </Accordion>

  <Accordion title="结束旧版本支持时">
    * [ ] 在 CHANGELOG/README 中明确写出停止支持
    * [ ] 从 `composer.json` 中移除旧版本约束
    * [ ] 从测试矩阵中移除旧版本
    * [ ] 清理旧版本相关的条件分支代码
  </Accordion>
</AccordionGroup>

## 相关页面

<Columns cols={2}>
  <Card title="包开发基础" icon="box" href="/zh/advanced/package-development">
    以 Service Provider 为核心讲解 Laravel 包的开发方法。
  </Card>

  <Card title="使用 Pest 进行进阶测试" icon="flask-conical" href="/zh/advanced/testing-pest">
    讲解使用 Pest 的 Expectation API 与数据集来编写包测试的方法。
  </Card>
</Columns>


## Related topics

- [包的 CHANGELOG 与发布管理](/zh/advanced/package-changelog.md)
- [使用 Orchestra Testbench 测试 Laravel 包](/zh/advanced/package-testing.md)
- [GitHub Actions 的固定与安全](/zh/advanced/github-actions-pinning.md)
- [延迟 Service Provider](/zh/advanced/deferred-provider.md)
- [包的静态分析（PHPStan / Larastan）](/zh/advanced/package-static-analysis.md)