LaravelAPI新手如何部署_Laravel本地与服务器部署流程【指南】-Laravel-PHP中文网

本地开发不必强制使用homestead或valet，但php内置服务器不支持重写规则、https、cors等真实环境特性；api项目涉及中间件、跨域、队列等时应切换至valet（macos）或docker。

laravelapi新手如何部署_laravel本地与服务器部署流程【指南】

不是必须，但不推荐直接用 PHP 内置服务器跑 API 项目。它不支持重写规则，api.php 路由会 404；也没法模拟真实 Nginx/Apache 的请求头、HTTPS、CORS 行为。

实操建议：

Laravel Creem Agent

Creem 支付商店助理 — 查询订阅、客户、交易、产品，执行心跳检查，管理本地 Laravel支付商店。

下载

开发阶段优先用 php artisan serve --host=0.0.0.0 --port=8000 快速验证逻辑，但仅限单路由、无中间件依赖的简单场景
涉及 Sanctum、Passport、跨域、队列或文件上传时，立刻切到 Valet（macOS）或 Docker（跨平台），否则你会在部署前反复踩 TokenMismatchException 或 CORS header ‘Access-Control-Allow-Origin’ missing
别在本地用 APP_URL=http://localhost 配置 API 前端调用——前端发请求时 Host 是 localhost，但 Laravel 生成的 JWT 或密码重置链接会漏掉端口，导致链接打不开

不能直接上传本地 .env，更不能 git commit。线上环境变量必须通过系统级注入，否则容易泄露数据库密码或 APP_KEY。

实操建议：

在服务器上运行 php artisan key:generate --show 拿到新 APP_KEY，再手动设为环境变量：export APP_KEY=base64:xxx（systemd 服务需写进 Environment= 字段）
Nginx + PHP-FPM 场景下，在 www.conf 里加：env[APP_ENV] = "production"、env[DB_HOST] = "127.0.0.1"，而不是靠 .env 文件
如果用 Forge / Envoyer，它们会在部署时自动把密钥注入 PHP-FPM 环境，此时要删掉项目根目录下的 .env，否则 Dotenv::createUnsafeImmutable() 仍会加载它并覆盖系统变量

因为缓存命令要求所有配置值可序列化，而新手常把闭包、对象或未初始化的变量塞进 config/*.php 里——比如在 config/services.php 中直接 new 一个 HTTP 客户端实例。

实操建议：

执行前先跑 php -l config/app.php 检查语法，再用 php artisan config:clear 清掉旧缓存，避免残留错误配置干扰
config:cache 只对 production 环境有效，APP_ENV=local 下它会静默跳过——所以别在本地测试完就以为上线没问题
API 项目尤其注意 config/cors.php：如果用了 env('ALLOW_ORIGINS') 但没在服务器设该变量，缓存后整个 API 就拒绝所有跨域请求，错误现象是浏览器控制台只显示 Failed to fetch，没有具体 CORS 报错

大概率是 PHP 错误被吞了，或者日志权限不对。Laravel 默认把错误输出关了，而生产环境又不显示详细错误页。

实操建议：

先确认 APP_DEBUG=false，然后看 storage/logs/laravel.log 最后几行——但注意：如果 storage 目录属主不是 PHP-FPM 进程用户（如 www-data），日志根本写不进去
临时打开调试：在 bootstrap/app.php 顶部加 error_reporting(E_ALL); ini_set('display_errors', '1');，再 curl 接口看原始报错，定位到具体哪行 PHP 语法或扩展缺失（比如忘了装 php-sqlite3 却在 config 中启用了 sqlite）
用 php -m | grep mbstring 确认必要扩展已启用——API 返回 JSON 乱码、json_encode() 失败、Str::slug() 报错，八成是 mbstring 或 openssl 缺失