composer require Telescope 失败主因是版本不兼容：laravel 8 用 ^4.0，9 用 ^4.17+，10.26+ 才可用 ^5.0；安装后需手动注册服务提供者、适配 mysql 字符集与引擎，并确保 app_ENV=local 且权限配置正确。
composer require 时为什么 Telescope 安装失败？
直接运行 composer require laravel/telescope --dev 失败，大概率是当前 Laravel 版本与 Telescope 不兼容。Telescope v4 要求 Laravel 9+，v5 要求 Laravel 10.26+，而旧项目常用 Laravel 8 或更早版本——此时必须指定兼容版本，否则 Composer 会因依赖冲突中止。
- 查清当前 Laravel 版本：
php artisan --version - Laravel 8 → 用 Telescope v4：
composer require laravel/telescope:^4.0 --dev - Laravel 9 → 优先用 v4.17+（含 PHP 8.1 兼容修复）：
composer require laravel/telescope:^4.17 --dev - Laravel 10.26+ → 可用 v5：
composer require laravel/telescope:^5.0 --dev
安装后执行 php artisan telescope:install 报错 “class ‘LaravelTelescopeTelescopeServiceProvider’ not found”
这是 Laravel 从 v5.5 升级到 v5.6+ 后自动发现机制变化导致的：新版本默认不自动注册 --dev 包的服务提供者。Telescope 的服务提供者未被加载，所以命令找不到类。
- 手动在
config/app.php的'providers'数组末尾添加：LaravelTelescopeTelescopeServiceProvider::class - 再运行
php artisan telescope:install才能成功生成配置和迁移 - 注意：Laravel 11 默认关闭包自动发现，此步骤不可跳过；Laravel 9/10 若项目禁用了
extra.laravel.dont-discover则可能跳过，但显式注册更稳妥
运行 migrate 报错 “SQLSTATE[HY000]: General Error: 1005 Can’t create table `telescope_entries`”
MySQL 默认引擎或字符集不兼容。Telescope v4+ 迁移使用 utf8mb4_unicode_ci 排序规则，且要求行格式为 DYNAMIC，老旧 MySQL 5.6 或未调优的 mariadb 常卡在这里。
- 临时解决（开发环境）：编辑
database/migrations/2018_08_08_100000_create_telescope_entries_table.php，在Schema::create后加一行：$table->engine = 'InnoDB'; - 根本解决：确认 MySQL 配置含
innodb_file_format = Barracuda和innodb_large_prefix = ON，并设数据库默认字符集为utf8mb4 - 若用 sqlite 开发，需确保
DB_CONNECTION=sqlite且database/database.sqlite可写，否则迁移会静默失败
访问 /telescope 页面显示 404 或 “this action is unauthorized.”
Telescope 默认只对本地环境（APP_ENV=local）且认证用户开放，并做了中间件拦截。生产环境即使强行启用也会被拒绝。
- 确认
.env中APP_ENV=local，且已执行php artisan config:clear - 检查
app/Providers/TelescopeServiceProvider.php中的gate()回调是否被注释或修改；默认只允许local环境下的管理员（user->isSuperAdmin()这类自定义逻辑会破坏权限） - 最简调试法：临时替换
gate()内容为：Gate::define('viewTelescope', function ($user) { return true; });，验证页面能否打开，再逐步收紧权限
Telescope 的核心陷阱不在安装命令本身，而在环境判断、服务注册时机和数据库底层约束这三处。很多人卡在“明明装上了却打不开”，其实问题早发生在 composer require 选错版本，或 telescope:install 前忘了改 config/app.php。