在 Web 开发中，Laravel 框架的高效便捷与宝塔面板 + Docker 的部署优势结合，能大幅简化环境搭建流程。但实际操作中，诸多细节疏忽会导致安装卡壳、项目无法运行。本文完全基于实操流程，梳理从环境配置到项目启动的全环节操作步骤与核心坑点，帮你避开每一个易踩的 “陷阱”。


第一步：创建 Laravel 专属扩展模板与运行环境​


1.1 扩展模板配置（奠定环境基础）​

进入宝塔面板后，首先需为 Laravel 创建专属扩展模板，避免后续环境缺失：​

操作路径：找到「Docker 管理器」-「扩展模板」，点击「创建模板」，命名为 “my-laravel”；​

扩展选择：根据项目需求添加必要扩展（用不到的可不选），版本必须指定为 PHP 8.3（适配当前主流 Laravel 版本，避免版本不兼容）；

pdo_mysql,xsl,calendar,bcmath

保存模板：确认扩展与版本后，点击「提交」完成模板创建。​


1.2 运行环境创建（绑定专属模板）​

模板创建后，需基于此模板生成项目运行环境：​

操作路径：「Docker 管理器」-「运行环境」-「创建环境」；​

关键配置：输入环境名称（如 “laravel-env-83”），版本选择 “PHP 8.3”，模板下拉选择刚刚创建的 “my-laravel”；

确认创建：点击「确认」，等待环境构建完成（此步骤若未选对模板，后续需重新配置，浪费时间）。


第二步：项目创建与基础配置（避坑第一步）


2.1 项目创建：绑定专属运行环境​

  • 操作路径：宝塔面板「网站」-「添加站点」，输入域名、设置根目录；​
  • 核心选择：「运行环境」下拉框，必须选中第一步创建的 “laravel-env-83”（若选默认环境，会出现 PHP 版本不匹配问题）；​
  • 提交创建：完成基础信息填写后，点击「提交」。​
  • 2.2 关键配置：伪静态与运行目录​
  • 这两项配置错误会直接导致项目无法访问，必须严格操作：​
  • 伪静态设置：进入刚创建的站点，点击「伪静态」，选择「Laravel」预设规则（若手动配置易出错，直接用预设模板）；​
  • 运行目录调整：进入站点「设置」-「网站目录」，将「运行目录」改为 “public”（Laravel 入口文件在 public 目录，不修改会出现 “403 禁止访问”），点击「保存」。


第三步：自定义网络环境（避免端口与 IP 冲突）

3.1 创建专属网段（隔离不同服务）​

为避免后续数据库、Redis 与其他容器 IP 冲突，需单独创建网段：​

  • 操作路径：「Docker 管理器」-「网络」-「创建网络」；​
  • 配置参数：网络类型选择 “桥接模式”，自定义网段（如 “188.88.0.0/24”，可按个人喜好设置，便于记忆），命名为 “laravel-net”；​
  • 确认创建：点击「提交」，完成专属网络搭建。

第四步：数据库与 Redis 容器创建（核心避坑点）


4.1 MySQL 容器创建（避坑：初始密码与端口配置）​

MySQL 容器若不配置初始密码，会直接启动失败，这是高频坑点：​

  • 操作路径：「Docker 管理器」-「容器」-「创建容器」；​
  • 基础配置：​
  • 镜像选择：搜索 “mysql”（选官方镜像，避免第三方镜像兼容性问题），版本建议选 “8.0”（适配 Laravel 10+）；​
  • 容器名称：自定义（如 “laravel-mysql”，便于区分）；​
  • 端口映射（关键！本地连接必配）：​
  • 对外暴露：勾选「对外暴露」（本地需连接服务器数据库时必须开启）；​
  • 端口配置：本地端口填 “23306”（避免与服务器自带 MySQL 的 3306 端口冲突），容器端口固定填 “3306”（MySQL 默认端口，不可修改）；​
  • 网络配置：​
  • 选择网络：下拉框选第三步创建的 “laravel-net”；​
  • 固定 IP：设置为 “188.88.0.1”（前两段与网段一致，最后一段按顺序设置，便于记忆）；​
  • 避坑关键：添加初始密码环境变量​
  • 点击「更多设置」，下拉到「环境变量」，点击「添加变量」；​
  • 变量名填 “MYSQL_ROOT_PASSWORD”，变量值填自定义密码（如 “Laravel@123”，复杂度足够避免安全风险）；​
  • 确认创建：点击「提交」，等待容器启动（若未加初始密码，容器会反复重启，需删除后重新创建）。​
  • 4.2 Redis 容器创建（参考 MySQL 配置）​
  • 操作路径：同 MySQL 容器创建，搜索 “redis” 选择官方镜像，版本选 “7.0”；​
  • 端口配置：本地端口填 “26379”（避免与默认 6379 冲突），容器端口 “6379”；​
  • 网络配置：选 “laravel-net”，固定 IP“188.88.0.2”（与 MySQL IP 区分，最后一段 + 1）；​
  • 确认创建：无需初始密码（简单场景），直接提交，完成 Redis 容器搭建。​
  • 4.3 PHP 容器 IP 调整（多程序需改端口）​
  • 若需部署多个 Laravel 项目，需调整 PHP-FPM 端口，避免冲突：​
  • 操作路径：「Docker 管理器」-「容器」，找到 PHP 容器（名称含 “laravel-env-83”），点击「编辑容器」；​
  • 网络调整：选择 “laravel-net” 网络，固定 IP“188.88.0.3”；​
  • 端口注意：默认 PHP-FPM 端口为 9000，若创建第二个 PHP 环境，需将端口改为 “9001”（否则两个 PHP 容器端口冲突，无法同时运行）；​
  • 保存修改：点击「提交」，重启容器生效。

避坑：mysql会因为没有初始密码，无法启动，需点击编辑容器->更多设置->拉到最下面，环境变量里添加如下代码

MYSQL_ROOT_PASSWORD=123456（自己设置的密码）

第五步：Laravel 配置与避坑收尾（关键两步）


5.1 .env 文件配置：数据库连接（IP 与端口必对）​

进入 Laravel 项目根目录，找到.env 文件，修改数据库配置：

在laravel里的env里设置mysql的链接，ip为188.88.0.1端口3306，按之前自己设置过的网段来配置。

避坑：建议提前开启php错误调试，php.ini里设置display_errors = On，路劲为：/www/dk_project/runtime/run/php/项目名/conf

5.2 提前开启 PHP 错误调试（便于后续排错）​

若不开启调试，出现错误时仅显示 “500 错误”，无法定位问题：​

找到 php.ini 路径：路径固定为/www/dk_project/runtime/run/php/项目名/conf/php.ini（需将 “项目名” 替换为实际 PHP 环境名称，如 “laravel-env-83”）；​

  • 修改配置：打开 php.ini，搜索 “display_errors”，将值改为 “On”（默认 Off），保存文件；​
  • 重启 PHP：进入「Docker 管理器」-「容器」，重启 PHP 容器，使配置生效。


第六步：避坑注意


6.1 Laravel 文件夹权限设置（调试日志依赖）​

开启错误调试后，若权限不足，会出现 “无法写入日志” 错误：​

  • 操作路径：进入 Laravel 项目根目录（如/www/wwwroot/laravel-project）；​
  • 权限设置：​
  • 右键点击文件夹，选择「权限」；​
  • 所有者设为 “www”，文件夹权限设为 “755”，文件权限设为 “644”；​
  • 重点：storage 和 bootstrap/cache 是 Laravel 核心读写目录，需单独强化权限 —— 右键这两个目录，将权限改为 “775”（仅这两个目录，其他目录无需过高权限，避免安全风险）；

6.2挂载卷路径错误（最易栽坑的隐藏问题）

当设置运行目录为 “public” 后，若直接使用默认挂载卷配置，会出现 “目录不存在” 或 “文件无法读取” 错误 —— 这是因为挂载路径会自动带上 “public” 后缀，与容器内实际路径冲突：​

  • 问题场景：创建 PHP 容器时，若项目运行目录设为 /www/wwwroot/laravel-project/public，默认挂载卷会显示 “本地目录：/www/wwwroot/laravel-project/public -> 容器目录：/var/www/html/public”，导致容器内无法识别 public 上级目录的核心文件（如 .env、vendor）；​
  • 避坑解决方案：​
  1. 进入「Docker 管理器」-「容器」，找到对应 PHP 容器，点击「编辑容器」；​

2. 下拉到「目录挂载」选项，找到已添加的挂载记录；​

3.同时删除本地目录和容器目录末尾的 /public—— 修改后应为 “本地目录：/www/wwwroot/laravel-project -> 容器目录：/var/www/html”；​

关键提醒：修改后需重新确认运行目录 —— 进入站点「设置」-「网站目录」，确保「运行目录」仍为 “public”（此时容器内 /var/www/html/public 路径与站点配置对应，既解决挂载冲突，又不影响入口文件访问）；​

点击「提交」保存容器修改，重启 PHP 容器生效（不重启则挂载配置不更新）。


核心避坑点总结（快速备查）​

  1. MySQL 必加初始密码：通过环境变量 MYSQL_ROOT_PASSWORD 配置，否则容器无法启动；​
  2. .env 数据库端口填容器端口：DB_PORT 为 3306（容器内端口），而非本地映射的 23306；​
  3. 挂载卷需删除 /public 后缀：运行目录设为 public，但挂载路径需指向项目根目录，避免路径冲突；​
  4. storage 和 bootstrap/cache 权限设 775：仅这两个目录需高权限，其他目录保持 755/644 兼顾安全与读写；​
  5. 多 PHP 容器改 FPM 端口：第二个 PHP 环境的 FPM 端口设为 9001，避免与 9000 冲突。

宝塔 Docker 安装 Laravel 的核心难点不在于 “步骤复杂”，而在于 “细节容错率低”—— 一个端口填错、一次权限遗漏、一条挂载路径错误，都可能导致全流程卡壳。本文通过 “操作步骤 + 坑点预警 + 解决方案” 的结构，覆盖从模板创建到数据库验证的全环节，只要严格按流程执行，就能避开 90% 以上的实操问题，快速搭建稳定的 Laravel 开发 / 生产环境。​


返回列表