中文

网站托管

在 Plesk 上托管 Laravel 网站

在 Plesk 上线 Laravel 应用程序,可使用或不使用 Laravel Toolkit:PHP 版本、数据库、.env 文件、迁移、计划任务和常见错误。

阅读约 9 分钟, 更新于 2026年11月18日

本页内容

您的参数

只需填写一次,指南中的命令会自动更新。

本指南介绍如何将 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 版本

  1. 进入 网站与域名,找到您的域名。
  2. 打开 PHP(或 PHP 设置,取决于您的 Plesk 版本)。
  3. 选择兼容的版本,然后保存。

步骤 2:创建数据库

请按照创建数据库指南创建数据库和专用用户。记下数据库名称、用户名、密码,以及 Plesk 在该数据库连接信息中显示的主机。

方法 1:使用 Laravel Toolkit

安装应用程序

在 网站与域名 中,找到您的域名,点击 创建网站 > Laravel,然后选择:

  • 从远程 repository 安装:输入您的仓库 URL。如果是私有仓库,请将 Plesk 显示的公钥添加到您的仓库(具体操作请参阅从 GitHub 或 GitLab 部署)。然后点击 安装应用程序。
  • 安装框架:Plesk 会安装一个空白的 Laravel 应用程序。点击 安装应用程序;如果您已有项目,再通过 FTP 或文件管理器用您的文件替换这些文件。

如果您的应用程序已经位于托管空间中:

  1. 在 主机与 DNS > 主机 中,将 文档根目录 设为 /httpdocs/public,然后点击 保存。
  2. 返回 Dashboard 选项卡,点击 创建网站 > Laravel,然后点击 Cancel。
  3. 点击 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
optimize
  • key:generate --force 用于生成 APP_KEY 密钥。请仅在该值为空时运行:更改正在运行的网站的密钥会导致已加密的数据无法读取,并使用户退出登录。
  • migrate --force 用于创建数据表。默认情况下,Laravel 还会在其中存储会话、缓存和队列。
  • storage:link 使 public 磁盘上的文件可以被访问。
  • optimize 会缓存配置、路由、事件和视图。

部署更新

在 部署 选项卡中:

  1. 选择 部署模式:手动 或 自动。
  2. 在 部署方案 下,取消勾选不需要的步骤。
  3. 点击 部署。

通过 编辑脚本 按钮可以自定义部署过程,前提是该域名已允许 SSH 访问。

启用计划任务

任务在应用程序代码中定义,通常位于 routes/console.php,无法从 Plesk 创建。至少存在一个任务时,才会出现 计划任务 选项卡:请将其开关设为 启用。

启用队列

Laravel Toolkit 中的队列功能依赖数据库和计划任务,因此计划任务必须处于启用状态。

  1. 将 Plesk 集成包添加到 composer.json 的 require 部分,并确认它与您的 Laravel 版本兼容:

    JSON
    "plesk/ext-laravel-integration": "^7.0"
  2. 执行部署,然后提交更新后的 composer.lock 文件,并再次部署。

  3. 确认 .env 文件中包含 QUEUE_CONNECTION=database。

  4. 启用 维护模式。

  5. 在 Artisan 中运行 migrate --force。如果您的项目没有 jobs 表的迁移,请先运行 queue:table。

  6. 停用 维护模式,然后将 Queue 开关设为 启用。

方法 2:不使用 Laravel Toolkit

在您的计算机上准备项目

在项目目录中,安装生产环境依赖项并编译前端文件:

终端
composer install --no-dev --optimize-autoloader
npm ci
npm run build
php artisan key:generate --show

请保存最后一条命令显示的密钥,它以 base64: 开头。如果您的网站已在运行,请继续使用其现有密钥。

上传文件

  1. 将项目打包为 .zip 压缩文件,包含 vendor 和 public/build 目录,但不包含 node_modules 和本地的 .env 文件。

  2. 在 文件 中打开 httpdocs,上传压缩文件并勾选,点击 提取文件,然后将其删除。

  3. 在 httpdocs 中创建 .env 文件,内容参照方法 1 的示例,并加入您的密钥:

    配置
    APP_KEY=base64:YOUR_GENERATED_KEY

您也可以使用 FTP 账户上传文件。

设置文档根目录

  1. 在 网站与域名 中,打开您域名的 主机与 DNS > 主机。
  2. 将 文档根目录 设为 /httpdocs/public。
  3. 点击 保存。

执行 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 访问权限,请使用计划任务:

  1. 打开 计划任务,然后点击 添加任务。
  2. 选择 运行 PHP 脚本。
  3. 使用文件夹图标选择 httpdocs/artisan 文件。
  4. 在参数字段(with arguments)中输入 migrate --force。
  5. 选择网站使用的 PHP 版本。
  6. 点击 现在运行 并等待结果。

依次对 storage:link 和 optimize 重复此操作。之后您可以直接取消,无需保存该任务。

计划 Laravel 任务

如果您的应用程序使用调度器,请按上述方法创建一个 运行 PHP 脚本 任务,参数为 schedule:run,并以 Cron 格式设置以下频率:

文本
* * * * *

检查结果

  1. 打开 https://您的域名.com/:页面应显示您的应用程序。

  2. 测试 Laravel 的健康检查路由,较新的项目默认包含此路由:

    终端
    curl -i https://您的域名.com/up

    状态码 200 表示应用程序已启动且没有出错。

  3. 确认敏感文件没有暴露:https://您的域名.com/.env 绝不能显示您的配置。

  4. 测试一个使用数据库的页面,例如登录页面。

故障排除

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,然后重新部署。