套件的版本相容性管理

Laravel 每年 2 至 3 月左右進行主版本升級。對於套件開發者而言，快速完成新版本的支援是對整個生態系的貢獻，也是提升自身套件可靠度的重要活動。

本頁為套件開發基礎的姊妹頁。以套件開發的基本知識（服務提供者、composer.json 的結構等）為前提。

對 Laravel 主版本更新的因應

因應流程

更新 composer.json 的 require

將新版本加入相依範圍。若要繼續支援舊版本，可以 || 並列。

"require": {
    "php": "^8.2",
    "illuminate/support": "^12.0||^13.0"
}

若新版本的因應完成、要終止舊版本支援，則刪除舊有約束。

"require": {
    "php": "^8.3",
    "illuminate/support": "^13.0||^14.0"
}

透過相依 illuminate/support 等所需元件而非整個 illuminate/framework，可讓相依樹保持較小。

於新版本執行測試

於 local 或 CI 環境使用新的 Laravel 版本執行測試。

composer update
vendor/bin/pest

測試通過即可確認基本相容性。若未通過，需修正被變更的 API 或已刪除的方法。

於 GitHub Actions 測試 matrix 中加入新版本

於 CI 的測試 matrix 中加入 Laravel 的新版本，持續確認相容性。詳情請參考測試 matrix 的設定範例。

發布新版本因應

包含 composer.json 變更的新版本以 tag 發布。使用者只需 composer update 就能安裝於新的 Laravel 版本上。

參考官方套件

若對因應方式有疑問，參考 Laravel 官方套件的 composer.json 最為可靠。

這些套件由 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

"require": {
    "php": "^8.2",
    "illuminate/support": "^11.0||^12.0||^13.0"
}

若希望積極使用新的 PHP 功能

若要使用 PHP 8.3 以後的功能（型別化常數、新的隨機函式等），需判斷是否提升最低要求。提升最低要求在語意化版本上屬於破壞性變更，因此應於主版本升級時進行。

"require": {
    "php": "^8.3",
    "illuminate/support": "^12.0||^13.0"
}

若提升 PHP 最低要求，使用舊 PHP 的使用者將無法更新套件。務必於 README 或 CHANGELOG 明確標示以事先告知。

舊版本支援的終止策略

長期維持舊版本會增加維護成本。制定明確的支援政策，定期終止舊版本支援，有助於健康的套件營運。

終止支援的時機

一般做法是配合 Laravel 的支援期間。Laravel 對各版本提供 18 個月的 bug 修正、2 年的安全性修正支援。若套件也採相同政策，對使用者較易理解。

判斷基準	說明
Laravel 官方支援結束	於該 Laravel 版本支援結束時停止對應
使用情況	Packagist 的下載統計顯示舊版使用者減少時
功能追加的障礙	為對應舊版本使新功能實作複雜化時

在 README 中明確標示支援政策

為使用者可以正確持有期待值，於 README.md 記載支援政策。

## 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 需在多個 branch 修正
分支程式碼增加 — 依版本以條件分支吸收不同實作的複雜性
測試 matrix 肥大化 — CI 執行時間變長
安全性 patch 的複雜化 — 需安全地 backport 至舊版本

於整體生態系不斷升級的過程中，適當終止舊版本支援對促使使用者遷移至最新環境亦有效果。

早期因應的好處

若能於 Laravel 發布同時完成因應，使用者可立刻遷移至新版本。這是套件可靠度的重要訊號。

以開發版事前驗證

Laravel 不公開 beta/RC，但可透過指定 dev-master 或 @dev 安裝開發中的下一版。於主版本發布前確認運作，可實現 Zero-day 因應。

# 以 dev-master 安裝下一版
composer require laravel/framework:dev-master --no-update
composer update
vendor/bin/pest

或者也可以用 @dev 約束安裝。

composer require laravel/framework:^14.0@dev --no-update
composer update
vendor/bin/pest

透過將 minimum-stability 設為 dev，可解析與開發版的相依關係。

{
    "minimum-stability": "dev",
    "prefer-stable": true
}

指定 prefer-stable: true 後，若存在穩定版則會以穩定版優先。在以開發版測試的同時，仍能保證會自動切換至穩定版。

第一步只要變更 composer.json 即可

即便在完整相容性確認前，只要更新 composer.json 的相依範圍並發布，使用者就能夠安裝套件。

"illuminate/support": "^12.0||^13.0"

小的 bug 可以於發布後以 patch 版本修正。與其等待完美的因應，不如優先讓其能夠安裝。

掌握 Release 資訊的方法

以下是及時掌握新版本 Release 資訊的方法。

資訊來源	內容
GitHub Watch 功能	於儲存庫「Watch → Custom → Releases」接收 mail 通知。framework 以外主要套件也一併登錄較好
Laravel 官方部落格	主版本 Release 的公告與新功能解說
Laravel 官方文件升級指南	破壞性變更的清單
laravel/framework commit log	若要先行掌握下一版變更，可直接追 commit log

測試 matrix 的設定範例

以下為以 GitHub Actions 自動測試多個 Laravel 與 PHP 版本組合的 workflow 範例。

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 執行即可掌握是哪個版本組合出問題。

測試 matrix 的階段性更新

當新 Laravel 版本發布時，將其加入 matrix。當終止舊版本支援時，將其從 matrix 移除。

# 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 完整範例。

{
    "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
}

版本升級因應 Checklist

Laravel 新版本發布前

以開發版（dev-master / @dev）進行運作確認
以官方升級指南確認破壞性變更
於測試環境實作對新版本的因應
於測試 matrix 中加入新版本並於 CI 確認

Release 後的初期因應

於 composer.json 的 illuminate/* 要求加入新版本
視需要更新 PHP 要求
require-dev 的 orchestra/testbench 也更新為對應版本
為新版本打 tag 並反映至 Packagist
更新 README 的版本相容性表格

終止舊版本支援時

於 CHANGELOG/README 明確標示支援終止
從 composer.json 刪除舊版本的約束
從測試 matrix 移除舊版本
整理舊版本用的條件分支程式碼

套件開發基礎

說明以服務提供者為核心的 Laravel 套件開發方式。

使用 Pest 進行進階測試

說明使用 Pest 的 Expectation API 與 dataset 撰寫套件測試的方式。

最後修改於 2026年8月2日

延遲服務提供者

GitHub Actions 的 Pinning 與安全性

AI 開發

設計模式

套件開發

應用程式結構

Laravel 13 新功能

Eloquent 深入探索

驗證擴充

認證擴充

安全性

佇列

測試

對 Laravel 主版本更新的因應

因應流程

參考官方套件

PHP 版本要求的更新

若希望積極使用新的 PHP 功能

舊版本支援的終止策略

終止支援的時機

在 README 中明確標示支援政策

維持舊版本的成本

早期因應的好處

以開發版事前驗證

第一步只要變更 composer.json 即可

掌握 Release 資訊的方法

測試 matrix 的設定範例

fail-fast: false 的重要性

測試 matrix 的階段性更新

composer.json 的範例

版本升級因應 Checklist

相關頁面

套件開發基礎

使用 Pest 進行進階測試

​對 Laravel 主版本更新的因應

​因應流程

​參考官方套件

​PHP 版本要求的更新

​若希望積極使用新的 PHP 功能

​舊版本支援的終止策略

​終止支援的時機

​在 README 中明確標示支援政策

​維持舊版本的成本

​早期因應的好處

​以開發版事前驗證

​第一步只要變更 composer.json 即可

​掌握 Release 資訊的方法

​測試 matrix 的設定範例

​fail-fast: false 的重要性

​測試 matrix 的階段性更新

​composer.json 的範例

​版本升級因應 Checklist

​相關頁面

套件開發基礎

使用 Pest 進行進階測試

對 Laravel 主版本更新的因應

因應流程

參考官方套件

PHP 版本要求的更新

若希望積極使用新的 PHP 功能

舊版本支援的終止策略

終止支援的時機

在 README 中明確標示支援政策

維持舊版本的成本

早期因應的好處

以開發版事前驗證

第一步只要變更 composer.json 即可

掌握 Release 資訊的方法

測試 matrix 的設定範例

fail-fast: false 的重要性

測試 matrix 的階段性更新

composer.json 的範例

版本升級因應 Checklist

相關頁面