Laravel UI 迁移指南：从旧版本平滑升级到最新版的完整教程

【免费下载链接】ui Laravel UI utilities and presets. 项目地址: https://gitcode.com/gh_mirrors/ui5/ui

Laravel UI 是一个提供基本身份验证和前端脚手架的工具包，支持 Bootstrap、Vue 和 React。随着 Laravel 框架的不断发展，Laravel UI 也经历了多次重大版本更新，特别是从 v3.x 到 v4.x 的迁移引入了 Vite 构建工具和 PHP 8+ 支持。本文将为您提供从旧版本平滑升级到最新版 Laravel UI 的完整指南。🚀

📊 Laravel UI 版本兼容性概览

在开始迁移之前，了解不同 Laravel UI 版本与 Laravel 框架的兼容性至关重要：

Laravel UI 版本	支持的 Laravel 版本	主要特性
1.x	Laravel 5.8, 6.x	基础身份验证脚手架
2.x	Laravel 7.x	改进的路由和控制器
3.x	Laravel 8.x, 9.x	Bootstrap 5 支持，Mix 6 配置
4.x	Laravel 9.x, 10.x, 11.x	Vite 支持，PHP 8+ 要求

🔧 迁移前准备工作

在开始迁移之前，请确保完成以下准备工作：

1. 备份现有项目：创建完整的项目备份，包括数据库和配置文件
2. 检查依赖版本：确认当前 Laravel 版本和 PHP 版本符合目标版本要求
3. 查看变更日志：详细阅读 CHANGELOG.md 了解所有破坏性变更

📦 从 Laravel UI 3.x 迁移到 4.x

1. 更新 Composer 依赖

从 Laravel UI 3.x 迁移到 4.x 的最大变化是引入了 Vite 作为默认构建工具。首先更新您的 composer.json：

# 移除旧版本
composer remove laravel/ui

# 安装最新版本
composer require laravel/ui

2. 更新前端构建工具

Laravel UI 4.x 使用 Vite 替代了 Laravel Mix。您需要更新前端依赖和配置文件：

# 更新 package.json 中的依赖
npm uninstall laravel-mix
npm install --save-dev vite @vitejs/plugin-vue

3. 配置文件迁移

Vite 配置文件：新的 vite.config.js 文件位于 src/Presets/bootstrap-stubs/vite.config.js，需要替换原有的 webpack.mix.js。

Bootstrap 版本更新：Laravel UI 4.x 使用 Bootstrap 5.2.3+，确保更新相关依赖：

{
  "dependencies": {
    "bootstrap": "^5.2.3",
    "@popperjs/core": "^2.11.6"
  }
}

4. 身份验证控制器更新

检查您的身份验证控制器是否使用了最新的特性。最新版本位于 auth-backend/ 目录中，包括：

• AuthenticatesUsers.php
• RegistersUsers.php
• ResetsPasswords.php

🚀 从 Laravel UI 2.x 迁移到 3.x

1. Bootstrap 4 到 Bootstrap 5

Laravel UI 3.x 将 Bootstrap 从版本 4 升级到版本 5，这涉及一些类名的变更：

<!-- 旧版本 (Bootstrap 4) -->
<div class="form-row">
  <div class="col-md-6">
    <!-- 内容 -->
  </div>
</div>

<!-- 新版本 (Bootstrap 5) -->
<div class="row">
  <div class="col-md-6">
    <!-- 内容 -->
  </div>
</div>

2. 表单验证改进

Laravel UI 3.x 改进了表单验证和错误处理，确保您的表单使用最新的验证规则。

🔄 处理常见迁移问题

问题 1：Vite 构建失败

解决方案：确保正确配置了 vite.config.js，并安装了所有必要的依赖：

// vite.config.js 示例配置
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/sass/app.scss', 'resources/js/app.js'],
            refresh: true,
        }),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

问题 2：CSS 类名不兼容

解决方案：Bootstrap 5 移除了一些类名，需要手动更新：

• .text-left → .text-start
• .text-right → .text-end
• .float-left → .float-start
• .float-right → .float-end

问题 3：JavaScript 组件不工作

解决方案：确保正确导入和注册 Vue/React 组件：

// resources/js/app.js
import { createApp } from 'vue';
import ExampleComponent from './components/ExampleComponent.vue';

const app = createApp({});
app.component('example-component', ExampleComponent);
app.mount('#app');

📝 迁移检查清单

在完成迁移后，请检查以下项目：

•  所有身份验证功能正常工作
•  前端资源正确编译
•  Bootstrap 5 样式正确应用
•  Vue/React 组件正常工作
•  表单验证和错误处理正常
•  响应式设计在不同设备上表现良好

🛠️ 自定义预设迁移

如果您创建了自定义预设，需要更新它们以兼容新版本：

// 自定义预设示例
use Laravel\Ui\UiCommand;

UiCommand::macro('custom-preset', function (UiCommand $command) {
    // 更新预设逻辑以兼容 Laravel UI 4.x
    $command->call('vendor:publish', [
        '--tag' => 'custom-preset-assets',
        '--force' => true,
    ]);
});

🎯 迁移最佳实践

1. 分阶段迁移

不要一次性迁移所有内容，建议分阶段进行：

1. 更新 Composer 依赖
2. 更新前端构建工具
3. 更新视图和样式
4. 测试所有功能

2. 使用版本控制

确保使用 Git 或其他版本控制系统，便于回滚到之前的版本。

3. 充分测试

迁移后进行全面测试，包括：

• 单元测试
• 功能测试
• 浏览器兼容性测试

4. 监控性能

迁移后监控应用程序性能，确保没有性能下降。

📚 相关资源

• 官方文档：查看 README.md 获取最新安装和使用指南
• 变更日志：详细阅读 CHANGELOG.md 了解所有版本变更
• 预设文件：参考 src/Presets/ 目录中的预设实现
• 身份验证后端：查看 auth-backend/ 目录中的身份验证逻辑

🎉 迁移成功后的优化

成功迁移到最新版 Laravel UI 后，您可以享受以下新特性：

1. 更快的构建速度：Vite 提供极快的热重载和构建速度
2. 现代前端工具链：支持最新的 JavaScript 和 CSS 特性
3. 更好的开发者体验：改进的错误报告和调试工具
4. 更好的性能：优化的资源加载和代码分割

⚠️ 重要注意事项

1. Laravel UI 是遗留包：对于新项目，建议考虑使用 Laravel Breeze 或 Laravel Jetstream
2. PHP 版本要求：Laravel UI 4.x 需要 PHP 8.0 或更高版本
3. 长期支持：只有最新主要版本会接收错误修复

通过遵循本指南，您可以顺利将 Laravel UI 从旧版本迁移到最新版本，享受更好的性能和开发体验。如果您遇到任何问题，请参考项目的 GitHub Issues 或 Laravel 社区论坛获取帮助。💪

记住，成功的迁移需要仔细的计划和测试。祝您迁移顺利！

【免费下载链接】ui Laravel UI utilities and presets. 项目地址: https://gitcode.com/gh_mirrors/ui5/ui