Windows下Laravel项目部署到Gitee与Ubuntu服务器全流程

1. 项目概述

作为一名长期在Windows环境下开发Laravel项目的PHP开发者，我经常需要将本地开发的项目部署到线上服务器。最近在帮团队搭建一套标准化的代码托管和部署流程时，发现国内使用Gitee作为代码托管平台是个不错的选择，不仅访问速度快，而且完全符合国内开发者的使用习惯。

本文将详细介绍如何在Windows10系统下，将基于Laravel框架开发的网站推送到Gitee代码仓库，并在Ubuntu服务器上完成拉取和部署的全过程。这套方案特别适合中小型团队或个人开发者使用，能够有效管理代码版本，实现快速部署。

2. 环境准备与工具配置

2.1 服务器环境搭建

在开始之前，我们需要确保服务器已经配置好运行Laravel所需的环境。我推荐使用Ubuntu 24.04 LTS作为服务器操作系统，它提供了长期支持且稳定性有保障。

服务器需要安装以下组件：

• Apache2：作为Web服务器
• PHP 8.4：Laravel 10.x版本需要PHP 8.1+
• MySQL 8：数据库服务
• Git：版本控制工具
• Composer：PHP依赖管理工具

安装命令如下：

bash复制sudo apt update
sudo apt install apache2 mysql-server php8.4 libapache2-mod-php8.4 php8.4-mysql php8.4-mbstring php8.4-xml php8.4-zip php8.4-curl git

注意：安装完成后，建议运行sudo mysql_secure_installation来加强MySQL的安全性设置。

2.2 本地开发环境配置

在Windows开发机上，我们需要安装Git客户端。从Git官网(https://git-scm.com/)下载最新版本的Git for Windows安装包。

安装时需要注意以下几点：

1. 选择"Use Git from the command line and also from 3rd-party software"选项
2. 勾选"Git Bash Here"选项，方便在项目目录直接打开Git命令行
3. 建议使用默认的"Checkout as-is, commit as-is"行尾转换设置，避免跨平台换行符问题

安装完成后，可以在任意文件夹右键选择"Git Bash Here"来打开Git命令行窗口。

2.3 Gitee账号与仓库创建

访问Gitee官网(https://gitee.com/)注册账号并完成手机验证。创建新仓库时，务必不要勾选"初始化仓库"选项，因为我们是要上传已有的Laravel项目代码。

建议仓库命名与项目名称一致，例如如果项目名为"my-laravel-app"，则仓库名也设为"my-laravel-app"。

3. 本地项目推送至Gitee

3.1 初始化本地Git仓库

在项目根目录右键选择"Git Bash Here"打开命令行，执行以下命令初始化Git仓库：

bash复制git init

这会在项目目录下创建隐藏的.git文件夹，用于存储版本控制信息。

3.2 配置Git用户信息

设置全局Git用户信息（只需执行一次）：

bash复制git config --global user.name "你的Gitee用户名"
git config --global user.email "你的Gitee注册邮箱"

如果只想为当前项目设置特定的用户信息，可以去掉--global参数：

bash复制git config user.name "项目专用用户名"
git config user.email "项目专用邮箱"

3.3 解决跨平台换行符问题

Windows和Linux使用不同的行尾符(CRLF vs LF)，这可能导致Git警告。为了解决这个问题，可以执行：

bash复制git config --global core.autocrlf false
git rm -r --cached .

第一条命令禁用自动换行符转换，第二条命令清除Git缓存，确保后续操作不受之前缓存的影响。

3.4 添加文件并提交

Laravel项目通常自带.gitignore文件，它会自动忽略vendor目录、.env等不需要版本控制的文件。添加所有文件到暂存区：

bash复制git add .

然后提交到本地仓库：

bash复制git commit -m "Initial commit: Add Laravel project"

3.5 关联并推送到Gitee远程仓库

首先在Gitee仓库页面复制仓库地址（推荐使用SSH方式，更安全便捷）。然后在本地执行：

bash复制git remote add origin git@gitee.com:你的用户名/仓库名.git
git push -u origin master

第一次推送需要输入Gitee账号密码或配置SSH密钥。如果使用SSH方式，需要先在本地生成SSH密钥对：

bash复制ssh-keygen -t rsa -C "your_email@example.com"

然后将公钥(~/.ssh/id_rsa.pub内容)添加到Gitee账号的SSH密钥设置中。

4. 服务器端项目部署

4.1 服务器Git配置

登录服务器，首先确保Git已安装：

bash复制git --version

如果未安装，执行：

bash复制sudo apt update
sudo apt install git

同样需要配置Git用户信息：

bash复制git config --global user.name "服务器部署账号"
git config --global user.email "server@example.com"

4.2 克隆项目到服务器

进入Web服务器目录（通常是/var/www/）：

bash复制cd /var/www
sudo git clone git@gitee.com:你的用户名/仓库名.git

克隆完成后，重命名目录为更简洁的名称（可选）：

bash复制sudo mv 仓库名 my-laravel-app

4.3 安装PHP依赖

进入项目目录并安装Composer依赖：

bash复制cd /var/www/my-laravel-app
sudo composer install --no-dev

注意：生产环境使用--no-dev参数避免安装开发依赖，减少不必要的文件和安全风险。

4.4 配置环境变量

复制.env.example为.env并生成应用密钥：

bash复制sudo cp .env.example .env
sudo php artisan key:generate

然后编辑.env文件配置数据库连接等参数：

bash复制sudo nano .env

主要需要修改的配置包括：

• APP_ENV=production
• APP_DEBUG=false
• DB_CONNECTION=mysql
• DB_HOST=127.0.0.1
• DB_PORT=3306
• DB_DATABASE=数据库名
• DB_USERNAME=数据库用户
• DB_PASSWORD=数据库密码

4.5 设置目录权限

Laravel需要storage和bootstrap/cache目录有写权限：

bash复制sudo chown -R www-data:www-data /var/www/my-laravel-app/storage
sudo chown -R www-data:www-data /var/www/my-laravel-app/bootstrap/cache
sudo chmod -R 775 /var/www/my-laravel-app/storage
sudo chmod -R 775 /var/www/my-laravel-app/bootstrap/cache

4.6 配置Apache虚拟主机

创建新的虚拟主机配置文件：

bash复制sudo nano /etc/apache2/sites-available/my-laravel-app.conf

添加以下内容（根据实际情况修改）：

apache复制<VirtualHost *:80>
    ServerName your_domain.com
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/my-laravel-app/public

    <Directory /var/www/my-laravel-app/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

启用新站点和rewrite模块：

bash复制sudo a2ensite my-laravel-app.conf
sudo a2enmod rewrite

测试配置并重启Apache：

bash复制sudo apache2ctl configtest
sudo systemctl restart apache2

5. 常见问题与解决方案

5.1 Git推送失败问题

问题1：权限被拒绝(publickey)

• 原因：SSH密钥未正确配置
• 解决：检查服务器~/.ssh/id_rsa.pub内容是否已添加到Gitee账号的SSH密钥中

问题2：Large files detected

• 原因：尝试提交了大文件
• 解决：使用git rm --cached移除大文件，或使用Git LFS管理大文件

5.2 服务器部署问题

问题1：Composer安装失败

• 原因：PHP扩展缺失
• 解决：安装所需扩展，如php8.4-mbstring, php8.4-xml等

问题2：Apache 403 Forbidden

• 原因：目录权限不正确
• 解决：确保/var/www/my-laravel-app目录的权限设置正确

问题3：页面显示500错误

• 原因：通常.env配置错误或目录权限问题
• 解决：检查Apache错误日志(/var/log/apache2/error.log)定位具体问题

5.3 后续更新部署流程

代码更新后，服务器端可以通过以下命令拉取最新更改：

bash复制cd /var/www/my-laravel-app
sudo git pull origin master
sudo composer install --no-dev
sudo php artisan migrate --force  # 如果需要数据库迁移
sudo php artisan cache:clear
sudo php artisan view:clear

建议设置自动化部署脚本或使用Webhook实现自动部署，减少手动操作。

6. 优化建议与高级配置

6.1 使用部署脚本简化流程

创建deploy.sh脚本：

bash复制#!/bin/bash
cd /var/www/my-laravel-app
git pull origin master
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan cache:clear
php artisan view:clear

然后给执行权限：

bash复制sudo chmod +x /var/www/my-laravel-app/deploy.sh

6.2 配置Gitee Webhook自动部署

1. 在Gitee仓库设置中添加Webhook
2. 设置Payload URL为服务器接收推送的端点
3. 服务器端创建接收Webhook的脚本

6.3 生产环境安全加固

• 禁用PHP危险函数：编辑php.ini，设置disable_functions
• 配置防火墙：只开放必要端口
• 定期备份：设置数据库和代码的自动备份
• 启用HTTPS：使用Let's Encrypt免费SSL证书

这套部署方案经过多个项目的实际验证，能够满足大多数中小型Laravel项目的部署需求。根据项目规模的不同，可以进一步考虑使用Docker容器化部署或CI/CD流水线等更高级的方案。