在 Plesk 上托管 Laravel 网站
在 Plesk 上线 Laravel 应用程序,可使用或不使用 Laravel Toolkit:PHP 版本、数据库、.env 文件、迁移、计划任务和常见错误。
本页内容
您的参数
只需填写一次,指南中的命令会自动更新。
本指南介绍如何将 Laravel 应用程序发布到您的 Plesk 托管空间。文中提供两种方法:使用 Plesk 专为 Laravel 提供的工具 Laravel Toolkit,或在该工具不可用时手动部署。
前提条件
- 能够访问您的 Plesk 面板(参见连接到 Plesk 界面)。
- 一个已绑定到您的托管空间并指向该空间的域名。
- 与您的应用程序兼容的 PHP 版本。Laravel 13 要求 PHP 8.3 或更高版本。 对于其他 Laravel 版本,请查看
composer.json文件中的php一行。 - Laravel 所需的 PHP 扩展:Ctype、cURL、DOM、Fileinfo、Filter、Hash、Mbstring、OpenSSL、PCRE、PDO、Session、Tokenizer 和 XML,使用 MySQL 或 MariaDB 时还需要
pdo_mysql。 - 您的项目,存放在 Git 仓库中或您的计算机上。
本指南使用 httpdocs,这是主域名通常使用的目录。附加域名的目录可能不同:请在 主机与 DNS > 主机 中查看 文档根目录。
关键要点:public 目录
只有 Laravel 的 public 目录应当可以从 Web 访问。项目的其余部分包含 .env 文件,其中保存着您的密码和加密密钥。切勿将 index.php 移动到项目根目录:域名的 文档根目录 必须指向 public。
如果项目位于 httpdocs 中,应使用的值为 /httpdocs/public。
步骤 1:选择 PHP 版本
- 进入 网站与域名,找到您的域名。
- 打开 PHP(或 PHP 设置,取决于您的 Plesk 版本)。
- 选择兼容的版本,然后保存。
步骤 2:创建数据库
请按照创建数据库指南创建数据库和专用用户。记下数据库名称、用户名、密码,以及 Plesk 在该数据库连接信息中显示的主机。
方法 1:使用 Laravel Toolkit
安装应用程序
在 网站与域名 中,找到您的域名,点击 创建网站 > Laravel,然后选择:
- 从远程 repository 安装:输入您的仓库 URL。如果是私有仓库,请将 Plesk 显示的公钥添加到您的仓库(具体操作请参阅从 GitHub 或 GitLab 部署)。然后点击 安装应用程序。
- 安装框架:Plesk 会安装一个空白的 Laravel 应用程序。点击 安装应用程序;如果您已有项目,再通过 FTP 或文件管理器用您的文件替换这些文件。
如果您的应用程序已经位于托管空间中:
- 在 主机与 DNS > 主机 中,将 文档根目录 设为
/httpdocs/public,然后点击 保存。 - 返回 Dashboard 选项卡,点击 创建网站 > Laravel,然后点击 Cancel。
- 点击 Scan,让 Plesk 检测该应用程序。
配置 .env 文件
从您的域名打开 Laravel。点击 环境变量 (.env) 旁的 编辑,修改以下值,然后点击 更新:
APP_NAME="我的应用程序"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://您的域名.com
DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=database_name
DB_USERNAME=database_user
DB_PASSWORD=database_password运行 Artisan 命令
在 Artisan 选项卡中,逐条输入以下命令(不带 php artisan 前缀)并执行:
key:generate --force
migrate --force
storage:link
optimizekey:generate --force用于生成APP_KEY密钥。请仅在该值为空时运行:更改正在运行的网站的密钥会导致已加密的数据无法读取,并使用户退出登录。migrate --force用于创建数据表。默认情况下,Laravel 还会在其中存储会话、缓存和队列。storage:link使public磁盘上的文件可以被访问。optimize会缓存配置、路由、事件和视图。
部署更新
在 部署 选项卡中:
- 选择 部署模式:手动 或 自动。
- 在 部署方案 下,取消勾选不需要的步骤。
- 点击 部署。
通过 编辑脚本 按钮可以自定义部署过程,前提是该域名已允许 SSH 访问。
启用计划任务
任务在应用程序代码中定义,通常位于 routes/console.php,无法从 Plesk 创建。至少存在一个任务时,才会出现 计划任务 选项卡:请将其开关设为 启用。
启用队列
Laravel Toolkit 中的队列功能依赖数据库和计划任务,因此计划任务必须处于启用状态。
-
将 Plesk 集成包添加到
composer.json的require部分,并确认它与您的 Laravel 版本兼容:JSON"plesk/ext-laravel-integration": "^7.0" -
执行部署,然后提交更新后的
composer.lock文件,并再次部署。 -
确认
.env文件中包含QUEUE_CONNECTION=database。 -
启用 维护模式。
-
在 Artisan 中运行
migrate --force。如果您的项目没有jobs表的迁移,请先运行queue:table。 -
停用 维护模式,然后将 Queue 开关设为 启用。
方法 2:不使用 Laravel Toolkit
在您的计算机上准备项目
在项目目录中,安装生产环境依赖项并编译前端文件:
composer install --no-dev --optimize-autoloader
npm ci
npm run build
php artisan key:generate --show请保存最后一条命令显示的密钥,它以 base64: 开头。如果您的网站已在运行,请继续使用其现有密钥。
上传文件
-
将项目打包为
.zip压缩文件,包含vendor和public/build目录,但不包含node_modules和本地的.env文件。 -
在 文件 中打开
httpdocs,上传压缩文件并勾选,点击 提取文件,然后将其删除。 -
在
httpdocs中创建.env文件,内容参照方法 1 的示例,并加入您的密钥:配置APP_KEY=base64:YOUR_GENERATED_KEY
您也可以使用 FTP 账户上传文件。
设置文档根目录
- 在 网站与域名 中,打开您域名的 主机与 DNS > 主机。
- 将 文档根目录 设为
/httpdocs/public。 - 点击 保存。
执行 Artisan 命令
如果有 SSH 访问权限,请使用与网站所选版本对应的 PHP 可执行文件。单独的 php 命令可能指向其他版本:
cd httpdocs
/opt/plesk/php/8.3/bin/php artisan migrate --force
/opt/plesk/php/8.3/bin/php artisan storage:link
/opt/plesk/php/8.3/bin/php artisan optimize如果没有 SSH 访问权限,请使用计划任务:
- 打开 计划任务,然后点击 添加任务。
- 选择 运行 PHP 脚本。
- 使用文件夹图标选择
httpdocs/artisan文件。 - 在参数字段(with arguments)中输入
migrate --force。 - 选择网站使用的 PHP 版本。
- 点击 现在运行 并等待结果。
依次对 storage:link 和 optimize 重复此操作。之后您可以直接取消,无需保存该任务。
计划 Laravel 任务
如果您的应用程序使用调度器,请按上述方法创建一个 运行 PHP 脚本 任务,参数为 schedule:run,并以 Cron 格式设置以下频率:
* * * * *检查结果
-
打开
https://您的域名.com/:页面应显示您的应用程序。 -
测试 Laravel 的健康检查路由,较新的项目默认包含此路由:
终端curl -i https://您的域名.com/up状态码
200表示应用程序已启动且没有出错。 -
确认敏感文件没有暴露:
https://您的域名.com/.env绝不能显示您的配置。 -
测试一个使用数据库的页面,例如登录页面。
故障排除
500 错误且没有详细信息
通过文件管理器查看 storage/logs/laravel.log,或使用 Laravel Toolkit 的 日志 按钮。仅当日志信息不足时,才短暂启用 APP_DEBUG=true。
No application encryption key has been specified.
APP_KEY 变量为空或不存在。请使用 key:generate --force 生成,或粘贴在您的计算机上生成的密钥,然后运行 config:clear。
您对 .env 的修改未生效
配置已被缓存。请运行 optimize:clear,问题解决后再运行 optimize。
首页出现 403、404 错误或文件列表
文档根目录很可能没有指向 public。请确认其值为 /httpdocs/public。如果只有内页返回 404 错误,请确认 public/.htaccess 文件已上传。
Vite manifest not found at: .../public/build/manifest.json
前端文件尚未编译或上传。请运行 npm run build,然后上传 public/build 目录。
SQLSTATE[HY000] [1045] Access denied
数据库用户名或密码不正确,或者该用户未关联到此数据库。请修改 .env,然后运行 config:clear。如果密码包含空格或 # 字符,请用引号将其括起来。
SQLSTATE[HY000] [2002]
Laravel 无法连接到数据库服务器。请对照数据库的连接信息检查 DB_HOST 和 DB_PORT。如果消息中出现 No such file or directory 且使用的是 localhost,请尝试 DB_HOST=127.0.0.1。
SQLSTATE[42S02]:找不到 sessions 或 cache 表
尚未在此数据库上执行迁移。请运行 migrate --force。
storage 中出现 Failed to open stream: Permission denied
Laravel 必须能够写入 storage 和 bootstrap/cache。请在文件管理器中检查这些目录的权限。如果您无法修复,请联系技术支持。
Your Composer dependencies require a PHP version ">= 8.3.0"
网站或命令行使用的 PHP 版本过旧。请在 Plesk 中选择正确的版本;通过 SSH 操作时,请使用可执行文件的完整路径,例如 /opt/plesk/php/8.3/bin/php。
上传的图片返回 404 错误
指向公共存储的链接缺失,或在部署时丢失。请重新运行 storage:link。
未显示 计划任务 选项卡
只有当应用程序定义了至少一个任务时,才会显示此选项卡。请检查 routes/console.php,然后重新部署。