Laravel 托管：部署 Laravel 应用

简介

要在 Square Cloud 上开发和托管 Laravel 应用，遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程，从初始设置到生产环境部署。

前置条件

Square Cloud 账户：通过注册页面使用你的邮箱进行注册。
有效套餐：为你的应用提供专属资源和优化的性能。查看我们可用的套餐，选择最适合你需求的方案。

本指南运行在 PHP 运行时上。

创建项目

你的电脑上需要安装 PHP 和 Composer。使用 Composer 安装 Laravel 安装器：

composer global require laravel/installer

然后创建项目并启动开发服务器：

laravel new myapp
cd myapp
php artisan serve

开发服务器通常监听 http://localhost:8000。以下是 routes/web.php 中的一个基础路由：

routes/web.php

<?php

use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return 'Hello World from Laravel!';
});

构建生产版本

Composer 会在 Square Cloud 上通过下面的 START 命令安装你的 PHP 依赖。如果你的应用使用 Vite 构建前端资源（默认如此），请在创建 ZIP 之前运行 npm run build，以便包含 public/build 文件夹。

选择生产服务器

如果没有 START 命令，Square Cloud 会以项目根目录作为文档根目录运行 PHP 内置服务器（php -S 0.0.0.0:80）。Laravel 的文档根目录是 public/ 文件夹，因此你的路由会返回 404 错误，.env 等文件还可能被暴露。请务必设置运行 Laravel 自带服务器的 START 命令。

端口和主机

php artisan serve 需要在命令行中同时指定这两个值：--host=0.0.0.0 --port=80。如果没有 --host=0.0.0.0，它只会监听 127.0.0.1，你的网站会超时。

配置 Square Cloud

在项目根目录创建 squarecloud.app 文件：

squarecloud.app

MAIN=public/index.php
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My Laravel app
SUBDOMAIN=mylaravelapp
START=composer install --no-dev --optimize-autoloader && php artisan migrate --force && php artisan serve --host=0.0.0.0 --port=80

每次启动时，该命令会：

composer install --no-dev --optimize-autoloader 将生产依赖安装到 vendor/ 中。
php artisan migrate --force 应用待执行的数据库迁移。在生产环境中运行迁移必须加上 --force。
php artisan serve --host=0.0.0.0 --port=80 通过 Laravel 的路由器从 public/ 文件夹提供你的应用，监听 80 端口和所有网络接口。

MAIN=public/index.php 会选择 PHP 运行时。通过控制面板上传时，请设置相同的主文件和启动命令。

环境变量

通过控制面板或使用 squarecloud app env set，在应用中设置以下环境变量，而不是上传本地的 .env 文件：

变量	值
`APP_KEY`	`php artisan key:generate --show` 的输出
`APP_ENV`	`production`
`APP_DEBUG`	`false`（生产环境中绝不要设为 `true`）
`APP_URL`	你网站的地址，例如 `https://mylaravelapp.squareweb.app`
`DB_CONNECTION`、`DB_HOST`、`DB_PORT`、`DB_DATABASE`、`DB_USERNAME`、`DB_PASSWORD`	你的数据库连接。新的 Laravel 项目默认使用 SQLite

信任 Square Cloud 代理

Square Cloud 通过代理以 HTTPS 提供你的网站。要让 Laravel 生成 https:// 链接和资源 URL，请在 bootstrap/app.php 中信任该代理：

bootstrap/app.php

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})

使用 Swoole 获得更好的性能

php artisan serve 一次只能处理一个请求。对于更高的流量，PHP 运行时已经内置 Swoole：使用 Laravel Octane（composer require laravel/octane）在 Swoole 上运行你的应用。

Swoole

在 Square Cloud 上用 Swoole 运行 PHP 应用。

ZIP 中包含哪些文件

整个项目：app/、bootstrap/、config/、database/、public/（如果使用 Vite，包括 public/build）、resources/、routes/、storage/、artisan、composer.json 和 composer.lock。
squarecloud.app。

不要包含 vendor/ 和 node_modules/（Composer 会在服务器上安装 vendor/），也不要包含本地的 .env 文件。

部署并验证

通过控制面板

访问上传页面

访问上传页面并上传你的项目 zip 文件。

配置你的环境

上传 zip 后，你需要为项目配置名称、主文件或运行时环境以及其他设置。
如果你上传的是 Web 项目，请务必选择 “Web Publication” 并为项目设置子域名。

部署你的项目

最后，点击 “Deploy” 按钮，即可将项目托管到 Square Cloud。
部署完成后，你可以在控制面板中监控项目的状态和日志。

确认你的应用已上线

首次部署通常在一分钟内完成。在控制面板中，等待你的应用状态显示为运行中，并检查日志中是否有启动错误。
如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。

应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

通过 CLI

要使用此方法，你的项目根目录中需要有一个名为 squarecloud.app 的配置文件。它告诉 Square Cloud 如何运行你的应用。

配置文件指南

了解如何创建定义你应用环境的 squarecloud.app 配置文件。

安装 CLI

安装 Square Cloud CLI。如果你已经安装，运行同一条命令即可更新：

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

运行下面的命令。它会打开你的浏览器：在浏览器中批准登录后，CLI 即可使用。无需复制任何 API 密钥。如需在脚本和 CI 中使用，请参阅 CLI 身份验证。

squarecloud auth login

上传你的项目

在项目文件夹中运行下面的命令。CLI 会将当前文件夹打包为 zip（排除 squarecloud.ignore 中列出的内容）并上传：

squarecloud upload

要上传你自己创建的 zip，请通过 --file 传入：

squarecloud upload --file <path/to/zip>

确认你的应用已上线

首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志：

squarecloud app status
squarecloud app logs

如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。

应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

常见错误

自定义域名

若要使用自定义域名（例如 mysite.com）来代替默认 URL mysite.squareweb.app，你需要 Standard 计划或更高等级。默认 URL 由配置文件中的 SUBDOMAIN 字段决定。要连接你的域名，请参阅如何设置自己的域名。

最低内存要求

网站和 API 的最低要求为 512MB RAM，足以在静态运行时上托管静态构建产物。对于在服务器上渲染页面的应用（Next.js、Nuxt、Angular SSR 等），我们建议至少 1GB RAM。对于更大型的应用，请分配更多 RAM，以防止应用内存耗尽而崩溃。

找不到此站点。

请检查子域名/域名是否与 SUBDOMAIN 字段或自定义域名设置中配置的内容一致。如果你刚上传站点，请等待最多 60 秒，让 Square 启用首次访问。

站点响应超时……

你的服务器必须监听端口 80 和主机 0.0.0.0。Square Cloud 会在你的应用中设置 PORT（80）和 HOST（0.0.0.0）环境变量：请在代码中读取它们，而不要硬编码其他值。只监听 localhost 或 127.0.0.1 的服务器永远收不到请求。

No application encryption key has been specified

缺少 APP_KEY。请使用 php artisan key:generate --show 生成一个，将其设置为环境变量，然后重启应用。

后续步骤

环境变量

将密钥和设置放在代码之外，并在运行时读取。

自定义域名

在 Standard 及以上计划中，用你自己的域名提供应用。

故障排除

修复无法启动的应用或没有响应的站点。

有关 Laravel 的更多信息，请参阅 Laravel 官方文档。

联系我们

如果你仍然遇到技术问题，我们的专业支持团队可以为你提供帮助。联系我们，我们很乐意协助你解决任何问题，支持质量正是开发者给予 Square Cloud 4.9/5 评分（共 402 条评价）（Google 与 Trustpilot）的重要原因之一。

Bots

网站

API 与后端

数据库

自托管应用

指南

迁移指南

Laravel 托管：部署 Laravel 应用

简介

前置条件

创建项目

构建生产版本

选择生产服务器

端口和主机

配置 Square Cloud

环境变量

信任 Square Cloud 代理

使用 Swoole 获得更好的性能

Swoole

ZIP 中包含哪些文件

部署并验证

通过控制面板

通过 CLI

配置文件指南

常见错误

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

No application encryption key has been specified

后续步骤

环境变量

自定义域名

故障排除

联系我们

​简介

​前置条件

​创建项目

​构建生产版本

​选择生产服务器

​端口和主机

​配置 Square Cloud

​环境变量

​信任 Square Cloud 代理

​使用 Swoole 获得更好的性能

Swoole

​ZIP 中包含哪些文件

​部署并验证

​通过控制面板

​通过 CLI

配置文件指南

​常见错误

​自定义域名

​最低内存要求

​找不到此站点。

​站点响应超时……

​No application encryption key has been specified

​后续步骤

环境变量

自定义域名

故障排除

​联系我们

简介

前置条件

创建项目

构建生产版本

选择生产服务器

端口和主机

配置 Square Cloud

环境变量

信任 Square Cloud 代理

使用 Swoole 获得更好的性能

ZIP 中包含哪些文件

部署并验证

通过控制面板

通过 CLI

常见错误

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

No application encryption key has been specified

后续步骤

联系我们