做 Laravel 項目最尷尬的一個時刻就是本地php artisan serve跑得好好的給同事演示也沒問題結(jié)果一到部署就卡住。代碼在 Windows 10 上寫好怎么弄到服務器上用 U 盤拷貝用壓縮包上傳再解壓這些辦法也不是不行但一旦項目要更新你就得重復上傳整個文件夾時間一長誰也受不了。更專業(yè)的做法是讓 Gitee 當中間人本地把代碼推送到 Gitee服務器再從 Gitee 拉取代碼并完成部署。這篇文章就圍繞這條鏈路把 Windows 10 開發(fā)環(huán)境、Laravel 框架、Gitee 倉庫、服務器部署這四件事串起來講清楚適合項目已經(jīng)在本地跑通、但第一次面對“上線”這個動作的開發(fā)者。這個流程遠沒有想象的復雜。本質(zhì)上就三步本地和 Gitee 建立信任關系把代碼推上去服務器和 Gitee 也建立信任關系把代碼拉下來最后在服務器上補齊依賴、配置環(huán)境并讓網(wǎng)站跑起來。真正容易出問題的是第一遍走流程時那些不起眼的細節(jié)。比如分支名對不上、.env被提交進倉庫、服務器上storage目錄權(quán)限不對、Nginx 偽靜態(tài)沒配導致路由 404。我會把每一步的操作命令、配置文件和踩坑點都寫出來你跟著走一遍基本能避開 90% 的部署問題。1. 項目拆解從 Windows 10 到服務器Laravel 項目的完整交付鏈路1.1 為什么用“本地推送、服務器拉取”這套鏈路很多第一次接觸部署的人會問為什么不能直接在服務器上開發(fā)或者為什么不用 FTP 上傳代碼答案很簡單——這兩條路對 Laravel 這種框架項目來說都不可持續(xù)。直接在服務器上開發(fā)等于放棄本地開發(fā)環(huán)境的各種便利。你在 Windows 10 上裝了 IDE、調(diào)試工具、瀏覽器擴展這些在服務器上統(tǒng)統(tǒng)沒有。而且服務器通常是 Linux 系統(tǒng)你還要額外熟悉一套環(huán)境效率很低。用 FTP 上傳則更危險因為 Laravel 項目里有大量文件手動上傳很容易漏文件、傳錯目錄。更重要的是FTP 無法保留版本歷史——你改壞了代碼想回滾到上一個能跑的版本FTP 做不到。而“本地推送 → Gitee 中轉(zhuǎn) → 服務器拉取”這套鏈路本質(zhì)上是把 Git 的版本管理能力延伸到了部署環(huán)節(jié)。本地提交一次Gitee 上就多一個歷史版本。服務器拉取一次線上代碼就對應一個明確的提交記錄。出了問題git log一看就知道線上跑的是哪個版本git checkout就能回到上一個穩(wěn)定版。這套流程對單人開發(fā)有效對團隊協(xié)作更是剛需——Gitee 上的代碼倉庫可以接入成員管理、代碼審查、Issue 跟蹤這些是 FTP 和 U 盤拷貝給不了的東西。1.2 鏈路中三個角色各自要做的事這條鏈路里一共有三個角色開發(fā)機、Gitee 倉庫、服務器。很多人對部署的理解是“把文件放到服務器上”其實更準確的說法是“讓三個角色之間形成一套標準流程”。角色扮演方核心任務開發(fā)機Windows 10編寫 Laravel 代碼、本地調(diào)試、提交代碼并推送到遠程倉庫遠程倉庫Gitee托管代碼、保存版本歷史、作為開發(fā)機與服務器之間的中轉(zhuǎn)分發(fā)點服務器Linux Nginx PHP-FPM MySQL拉取代碼、安裝依賴、配置環(huán)境變量、對外提供 Web 服務有一點要特別說明Laravel 項目部署比靜態(tài)網(wǎng)頁或普通 PHP 項目更繁瑣原因在于它有三個典型特征。第一它依賴 Composer 管理外部包代碼倉庫里通常不包含vendor目錄服務器拉下來之后必須先安裝依賴第二它依賴環(huán)境變量配置數(shù)據(jù)庫、緩存、應用密鑰等信息.env文件不能直接放進 Git 倉庫服務器上需要單獨創(chuàng)建第三它的入口文件在public目錄下Web 服務器的根目錄必須指向public還要配好偽靜態(tài)規(guī)則才能支持 Laravel 的路由系統(tǒng)。把這三點理解了后面的部署操作就有清晰的目標了。2. 本地準備Windows 10 下的 Git 安裝、SSH 密鑰與 Gitee 連接2.1 安裝 Git 并配置全局參數(shù)Windows 10 上第一步是安裝 Git。直接去 Git 官網(wǎng)下載 Windows 版本的安裝包安裝時一路默認即可。有幾個選項可以留意一下默認編輯器建議保留 Vim 或者改成 Notepad不影響后面操作PATH 環(huán)境變量選擇 “Git from the command line and also from 3rd-party software” 那一項換行符轉(zhuǎn)換建議選 “Checkout as-is, commit as-is”這個選擇能減少一部分換行符問題后面我會專門講 CRLF 的坑。安裝完 Git 之后打開 Git Bash先配置身份信息。這一步很重要因為 Git 的每一次提交都會把這兩個信息寫進提交記錄里。如果不配置提交時會報錯或者生成一串占位信息到后面看歷史記錄時非常難受。git config --global user.name 你的名字 git config --global user.email 你的郵箱example.com強烈建議這里的郵箱和你在 Gitee 注冊時用的郵箱保持一致。這樣你推送到 Gitee 的提交記錄能直接關聯(lián)到你的 Gitee 賬號團隊協(xié)作時能看清誰提交了什么。配置完成后可以用git config --list檢查一下確認兩個參數(shù)都寫進去了。2.2 生成 SSH 密鑰并把公鑰加到 GiteeWindows 10 下連接 Gitee 有兩種協(xié)議可選HTTPS 和 SSH。HTTPS 每次推送都要輸賬號密碼雖然 Git 可以緩存憑證但換機器、換用戶時經(jīng)常會遇到憑證沖突。SSH 則是一次配置永久免密并且安全性更高——它通過公鑰和私鑰配對的方式驗證你的身份私鑰保存在本地公鑰放在 Gitee。生成 SSH 密鑰的命令是在 Git Bash 里執(zhí)行ssh-keygen -t rsa -b 4096 -C 你的郵箱example.com執(zhí)行后會出現(xiàn)提示讓你選擇保存路徑直接回車用默認路徑即可。默認路徑是C:\Users\你的用戶名\.ssh\id_rsa.pub其中id_rsa是私鑰id_rsa.pub是公鑰。再次強調(diào)私鑰絕對不能泄露、不能上傳到任何地方公鑰可以分發(fā)到 Gitee 等平臺。接著查看公鑰內(nèi)容cat ~/.ssh/id_rsa.pub輸出結(jié)果是一長串以ssh-rsa開頭、以你的郵箱結(jié)尾的字符串。復制它然后打開 Gitee 網(wǎng)站登錄后進入 設置 → 安全設置 → SSH 公鑰把復制的內(nèi)容粘貼進去起一個容易辨識的標題比如“Windows10-dev”保存即可。2.3 驗證連接與常見失敗處理配置好公鑰后在 Git Bash 里執(zhí)行下面的命令驗證是否連通ssh -T gitgitee.com第一次執(zhí)行時系統(tǒng)會提示無法確認 host 身份問你是否繼續(xù)連接輸入yes回車。如果配置正確會看到類似這樣的輸出Hi 你的用戶名! Youve successfully authenticated, but GITEE.COM does not provide shell access.這句提示的意思是認證成功但 Gitee 不提供 shell 登錄能力這很正常說明 SSH 密鑰已經(jīng)生效。我遇到過不少次Permission denied (publickey)的情況排查順序一般是檢查公鑰是否完整復制到了 Gitee檢查本機 SSH key 是否存在ls -la ~/.ssh確認你當前用的賬號和 Gitee 上添加公鑰的賬號是同一個。還有一種容易被忽略的情況如果你之前用 HTTPS 方式克隆過倉庫Git 會優(yōu)先嘗試 HTTPS 認證這時需要檢查倉庫的 remote 地址是不是gitgitee.com開頭的 SSH 格式。3. 推送實戰(zhàn)創(chuàng)建 Gitee 倉庫、配置 .gitignore 并完成首次提交3.1 創(chuàng)建 Gitee 倉庫時的幾個關鍵選擇SSH 配置好之后下一步是去 Gitee 上創(chuàng)建一個空倉庫。進入 Gitee 首頁點“新建倉庫”會看到幾個需要填的選項。倉庫名稱最好和項目名一致比如laravel-blog方便識別。路徑會自動生成一般不用改?！笆欠耖_源”這個選項要慎重開源倉庫是所有人都能看到的私有倉庫只有你和被你添加的成員能訪問。如果你的項目里含業(yè)務敏感信息或者暫時不想公開就選“私有”。下面有個初始化倉庫的選項里面包含是否自動生成 README 文件。我個人建議先不要勾選自動生成 README也不要在 Gitee 上勾選添加 .gitignore 模板。理由很簡單——如果你在 Gitee 上初始化了倉庫本地第一次推送時就會出現(xiàn)“兩邊各自有獨立提交歷史”的沖突。后面對新手來說處理起來很麻煩還要先 pull 再 push。先創(chuàng)建空倉庫本地直接推是最順滑的路徑。還要留意一個設置Gitee 創(chuàng)建倉庫時可以選“分支模型”默認是master還是main不同版本界面可能不一樣記住你選的這個分支名。后面本地倉庫初始化的時候要把本地分支名改成和遠程一致否則推送時會提示分支不匹配。3.2 Laravel 項目的 .gitignore哪些文件絕對不能進倉庫Laravel 項目創(chuàng)建時根目錄下已經(jīng)自帶了一份.gitignore文件。這份文件的作用是告訴 Git某些目錄和文件不要納入版本控制。你可千萬別覺得沒必要這是 Laravel 項目部署中幾乎最重要的防線。至少要確認下面這些內(nèi)容在.gitignore里/vendorComposer 安裝的依賴包每個環(huán)境都可以單獨執(zhí)行composer install生成不需要、也不應該進倉庫node_modules同理前端依賴由npm install或yarn生成.env環(huán)境變量文件包含數(shù)據(jù)庫密碼、APP_KEY 等敏感信息絕不能進倉庫/storage/*.key存儲目錄下的密鑰文件storage/logs/*.log日志文件.idea、.vscodeIDE 的本地配置不同開發(fā)者配置不同不該提交.phpunit.result.cache測試緩存如果你發(fā)現(xiàn)vendor已經(jīng)被提交進了倉庫不要慌用下面的命令把它從 Git 管理中移除但保留本地文件git rm -r --cached vendor git commit -m chore: remove vendor directory from version control這里特別強調(diào).env的問題。我在現(xiàn)實中見過不止一次因為.env被誤提交導致數(shù)據(jù)庫密碼、郵箱密碼泄露甚至 APP_KEY 被公開后攻擊者可以利用 Laravel 的加密機制反序列化執(zhí)行惡意代碼。既然項目默認的.gitignore已經(jīng)把你保護好了就不要再自己去把.env手動git add進去。3.3 首次推送到遠程倉庫完整命令流代碼準備就緒后開始首次推送。打開 Git Bash進入你的 Laravel 項目根目錄依次執(zhí)行# 初始化本地倉庫 git init # 統(tǒng)一分支名假設遠程倉庫分支模型是 main git branch -M main # 把所有文件加入暫存區(qū) git add . # 提交 git commit -m feat: 初始化 Laravel 項目 # 關聯(lián)遠程倉庫換成你自己的倉庫地址 git remote add origin gitgitee.com:你的用戶名/你的倉庫名.git # 推送并建立上游跟蹤 git push -u origin main關于git branch -M main這一步多解釋一句。不同版本的 Git 默認分支名不一樣有的是master有的是main如果不統(tǒng)一推送時 Git 會提示fatal: The current branch master has no upstream branch或者遠程拒絕推送。先加這個參數(shù)保證本地分支和遠程倉庫分支一致后面就不糾結(jié)了。推送成功后打開 Gitee 倉庫頁面就能看到代碼了。-u參數(shù)的含義是“建立上游跟蹤”意思是把本地main分支和遠程main分支關聯(lián)起來之后你再執(zhí)行g(shù)it push或git pull就不用再帶倉庫地址和分支名了。如果第一次推送就被拒絕rejected大概率是遠程倉庫里已經(jīng)有提交記錄了。解決思路很簡單如果你確認遠程倉庫是空的或不該有的可以把遠程倉庫清掉重建如果遠程倉庫里確實有你需要的內(nèi)容比如同事推過代碼那就先拉取再合并git pull --rebase origin main git push -u origin main4. 服務器部署從 Gitee 拉取代碼到 Nginx 站點上線4.1 服務器環(huán)境準備LNMP 還是寶塔面板代碼推送到 Gitee 之后主角切換到服務器。服務器操作系統(tǒng)一般用 Linux常見的有 Ubuntu、Debian、CentOS。以 Ubuntu 22.04 為例Laravel 10 要求 PHP 版本不低于 8.1這里我裝 PHP 8.2 比較穩(wěn)妥。服務器環(huán)境的搭建有兩條路線手動搭建 LNMPLinux Nginx MySQL PHP或者用寶塔面板這類可視化工具。兩者各有優(yōu)劣。寶塔面板對新手極度友好圖形界面上點一點就能裝好 Nginx、PHP、MySQL還能創(chuàng)建站點、管理 SSL 證書。我自己的建議是著急上線、不想折騰環(huán)境的用寶塔想理解部署原理、以后好排查問題的手動搭建。不管用哪條路線最終服務器上要有的核心軟件是固定的NginxWeb 服務器負責接收 HTTP 請求、轉(zhuǎn)發(fā)給 PHP 處理PHP 8.x PHP-FPMPHP 解釋器和進程管理器MySQL / MariaDB數(shù)據(jù)庫ComposerPHP 依賴管理工具Git用于從 Gitee 拉取代碼Ubuntu 上手動安裝這些軟件包的命令大概是這樣sudo apt update sudo apt install -y nginx sudo apt install -y php8.2-fpm php8.2-cli php8.2-mysql php8.2-mbstring php8.2-xml php8.2-curl php8.2-zip php8.2-bcmath php8.2-gd sudo apt install -y composer sudo apt install -y git注意 PHP 擴展我寫了一個列表這些是 Laravel 正常運行必需的。漏裝php8.2-mbstring會導致使用字符串處理時報錯漏裝php8.2-xml會導致一些依賴包安裝失敗漏裝php8.2-zip會直接影響composer install的執(zhí)行。安裝完成后用php -v驗證版本用php -m列出已加載的擴展。4.2 在服務器上生成 SSH 密鑰并從 Gitee 拉取代碼服務器上的代碼來源有兩種方式SSH 方式和 HTTPS 方式。HTTPS 方式最簡單克隆無需額外配置但之后每次git pull都可能要求輸入賬號密碼或 Token。SSH 方式需要做一次密鑰配置但配好之后一勞永逸。服務器上生成 SSH 密鑰ssh-keygen -t rsa -b 4096 -C deployexample.com生成后查看公鑰cat ~/.ssh/id_rsa.pub把輸出的公鑰添加到 Gitee。這里有一個細節(jié)不建議把服務器公鑰加在“個人 SSH 公鑰”列表里更好的做法是使用 Gitee 的“部署公鑰”功能。部署公鑰可以綁定到指定倉庫而且可以只給只讀權(quán)限這樣即使服務器被入侵也只是能拉取這個倉庫的代碼不能往別的倉庫推送東西風險可控。配置完成后把代碼克隆到服務器。我習慣統(tǒng)一放在/var/www目錄下sudo mkdir -p /var/www cd /var/www sudo git clone gitgitee.com:你的用戶名/你的倉庫名.git克隆完成后你會看到/var/www/你的倉庫名這個目錄。這里要立刻處理目錄權(quán)限問題。PHP-FPM 默認以www-data用戶運行如果項目目錄的屬主是 rootPHP 就沒有權(quán)限寫日志、寫緩存。我通常的做法是把項目目錄的屬主改成www-datasudo chown -R www-data:www-data /var/www/你的倉庫名這一步看起來不起眼但如果不做后面 Laravel 報“Permission denied”會讓你排查很久。4.3 安裝依賴與環(huán)境配置composer install、.env 與 key:generate代碼拉下來之后第一件要做的事就是安裝 PHP 依賴。因為 Laravel 項目的vendor目錄默認不進 Git 倉庫服務器上執(zhí)行cd /var/www/你的倉庫名 sudo -u www-data composer install --no-dev --optimize-autoloader這是手動搭建環(huán)境時比較推薦的順序。--no-dev表示不安裝開發(fā)環(huán)境依賴線上環(huán)境用不到phpunit、barryvdh/laravel-debugbar之類的包裝上去只會拖慢應用、增加被攻擊面。--optimize-autoloader會生成優(yōu)化過的自動加載映射讓 Laravel 加載類更快一點。接下來創(chuàng)建環(huán)境變量文件。Laravel 默認提供.env.example作為模板直接復制sudo -u www-data cp .env.example .env然后編輯.env把關鍵配置改成線上環(huán)境對應的值APP_NAME你的應用名 APP_ENVproduction APP_DEBUGfalse APP_URLhttps://你的域名 DB_CONNECTIONmysql DB_HOST127.0.0.1 DB_PORT3306 DB_DATABASE你的數(shù)據(jù)庫名 DB_USERNAME你的數(shù)據(jù)庫用戶 DB_PASSWORD你的數(shù)據(jù)庫密碼這里有一個新手很容易忽略的點.env修改完之后必須執(zhí)行sudo -u www-data php artisan key:generate這個命令會生成一個隨機的 32 位字符串寫入.env的APP_KEY字段。Laravel 用它做加密解密、session 簽名、cookie 加密。如果APP_KEY為空頁面會直接報錯No application encryption key has been specified。在本地用php artisan serve時 Laravel 會自動處理但到服務器上手動部署這一步必須自己執(zhí)行。如果項目有數(shù)據(jù)庫遷移可以順便跑一下sudo -u www-data php artisan migrate --force--force參數(shù)是在生產(chǎn)環(huán)境跳過確認提示因為這里不帶APP_ENVproduction的話migrate 會停下來問“你確定要在生產(chǎn)環(huán)境執(zhí)行嗎”。還要建一個軟鏈接讓public/storage能訪問到storage/app/public目錄sudo -u www-data php artisan storage:link如果你用了 Laravel 的Storage磁盤功能上傳過文件這一步一定要做不然前端訪問上傳圖片會 404。關于權(quán)限我再補一條硬性要求sudo chmod -R 775 storage bootstrap/cachestorage目錄要寫日志、編譯 Blade 模板、存 session 和緩存bootstrap/cache要存配置文件緩存。如果這兩個目錄不可寫頁面會白屏或報 500。4.4 Nginx 站點配置根目錄、偽靜態(tài)與 PHP-FPMLaravel 項目跑起來需要 Nginx 把請求交給 PHP-FPM 處理。Nginx 的站點配置文件一般放在/etc/nginx/sites-available/下然后在/etc/nginx/sites-enabled/里建軟鏈接啟用。創(chuàng)建一個站點配置比如/etc/nginx/sites-available/laravelserver { listen 80; server_name your-domain.com; root /var/www/你的倉庫名/public; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php8.2-fpm.sock; } location ~ /\.(?!well-known).* { deny all; } }逐個說明幾個關鍵配置。root指向的是/var/www/你的倉庫名/public而不是項目根目錄。因為 Laravel 的入口文件是public/index.php所有 HTTP 請求都必須經(jīng)過這個入口處理。如果把 root 指到項目根目錄用戶訪問時會把.env、storage等敏感目錄直接暴露出來非常危險。try_files $uri $uri/ /index.php?$query_string;是 Laravel 路由的偽靜態(tài)規(guī)則。它的邏輯是先嘗試把請求作為真實文件返回找不到再當作目錄處理還找不到就全部交給index.php由 Laravel 的路由系統(tǒng)解析。沒有這一行你訪問/about這種路由時會直接 404因為服務器上根本沒有about這個文件。location ~ \.php$這一段把以.php結(jié)尾的請求交給 PHP-FPM 處理。這里fastcgi_pass用的是 Unix socket具體路徑要看你的 PHP 版本Ubuntu 上 PHP 8.2 對應/run/php/php8.2-fpm.sock。如果你用的不是 Ubuntu 或者 PHP 版本不同用php -v或systemctl status php8.2-fpm查一下路徑。配置文件寫好之后測試語法再重載sudo nginx -t sudo systemctl reload nginx到這里如果域名 DNS 解析已經(jīng)指向服務器打開瀏覽器訪問你的域名Laravel 網(wǎng)站應該就能正常顯示了。5. 上線優(yōu)化部署后的緩存刷新與日常更新流程5.1 上線前的幾個必要設置網(wǎng)站能打開只是第一步上線前還要做幾個優(yōu)化設置否則后面的維護會比較折騰。Laravel 提供了一組緩存命令把配置、路由、視圖編譯成緩存文件提高整體響應速度sudo -u www-data php artisan config:cache sudo -u www-data php artisan route:cache sudo -u www-data php artisan view:cacheconfig:cache會把所有配置文件合并成一個緩存文件Laravel 加載配置時就不需要逐個讀取.env和config目錄了。route:cache同樣會把路由表打包生產(chǎn)環(huán)境能明顯降低路由匹配耗時。需要提醒的是執(zhí)行了config:cache之后你再修改.env文件配置不會立即生效。此時要執(zhí)行php artisan config:clear才能重新讀取環(huán)境變量。這個特性很多新人不知道容易在改完數(shù)據(jù)庫密碼后得到一個“數(shù)據(jù)庫連接錯誤”的 500 頁面。再把.env里的APP_ENVproduction和APP_DEBUGfalse確認一遍。APP_DEBUGtrue時一旦發(fā)生異常Laravel 會把堆棧信息、環(huán)境變量、數(shù)據(jù)庫連接信息打印在頁面上。這在本地開發(fā)是神器在生產(chǎn)環(huán)境就是定時炸彈——任何一個報錯頁面都會把你的服務器底細暴露給訪問者。如果條件允許建議順手把 Nginx 的 80 端口重定向到 443HTTPS。證書可以用 Let’s Encrypt 免費申請配置好后在.env里把APP_URL改成https://開頭同時再執(zhí)行一次php artisan config:cache刷新配置。HTTPS 對加密 Cookie、登錄狀態(tài)保護都很重要這個不能省。5.2 日常更新流程拉取、裝依賴、刷新緩存服務器上的 Laravel 項目上線之后你還會持續(xù)提交代碼。日常發(fā)布更新的標準流程也應該形成固定套路。本地開發(fā)機上正常提交并推送git add . git commit -m feat: 增加某功能 git push origin main服務器上拉取最新代碼并部署cd /var/www/你的倉庫名 sudo -u www-data git pull origin main sudo -u www-data composer install --no-dev --optimize-autoloader sudo -u www-data php artisan migrate --force sudo -u www-data php artisan config:clear sudo -u www-data php artisan route:clear sudo -u www-data php artisan view:clear sudo -u www-data php artisan config:cache sudo -u www-data php artisan route:cache sudo -u www-data php artisan view:cache如果你沒有修改數(shù)據(jù)庫結(jié)構(gòu)migrate可以不執(zhí)行如果你更新的代碼沒有新增配置項config:clear和后面的config:cache也可以跳過。但我的習慣是每次都執(zhí)行一套完整的部署命令因為有些第三方擴展在安裝時會向config目錄發(fā)布配置文件不刷新緩存會導致新配置不生效。注意到我用sudo -u www-data執(zhí)行所有命令而不是直接用 root 或普通用戶。原因前面提過PHP-FPM 以www-data用戶運行用它執(zhí)行這些命令生成的文件屬主就是www-dataPHP 才有權(quán)限讀寫。如果用 root 執(zhí)行composer install生成的vendor屬主是 rootPHP 訪問不到頁面照樣報錯。這里說一句實在話更新時最怕的不是代碼寫錯而是更新流程不固定。每次更新都靠“手動拖文件”或者“只傳改過的那幾個文件”遲早會漏掉東西。把所有發(fā)布動作固定成上面這一串命令做成一個腳本或?qū)懗晒P記每次照做線上出問題就能快速定位是哪一步出了問題。6. 常見問題排查本地推送、服務器拉取與部署的坑6.1 本地到 Gitee 的典型問題推送時報Permission denied (publickey)這個提示說明 Git 沒有找到有效的 SSH 密鑰或者 Gitee 不認可你的公鑰。檢查順序是本地~/.ssh/id_rsa.pub是否存在Gitee 后臺是否添加了正確的公鑰執(zhí)行ssh -T gitgitee.com看報什么錯。如果提示Host key verification failed是因為服務器指紋未確認重連并輸入yes即可。報failed to push some refs遠程倉庫有本地沒有的提交記錄。最常見的原因就是你在創(chuàng)建 Gitee 倉庫時勾選了自動生成 README 或 .gitignore。解決方法是先拉取合并再推送git pull --rebase origin main git push -u origin main--rebase會把本地的提交“接”到遠程提交的后面保持線性歷史比直接默認合并更干凈。推送時出現(xiàn)LF will be replaced by CRLF警告這是 Windows 和 Linux 換行符差異導致的。Windows 用CRLF回車換行Linux 用LF換行。Git 默認在 Windows 上會把LF轉(zhuǎn)成CRLF這個警告大多數(shù)情況下無影響。但如果項目里有 Bash 腳本被轉(zhuǎn)換后上傳到 Linux 服務器執(zhí)行會報$\r: command not found這種錯誤。解決方式是在項目根目錄加一個.gitattributes文件* textauto eollf *.sh text eollf這樣 Git 會把文本文件統(tǒng)一按LF提交服務器拉取后就不會有\(zhòng)r的干擾。6.2 服務器上的典型問題composer install報內(nèi)存不足服務器內(nèi)存太小或者 PHP 的memory_limit太小Composer 在解析依賴時會報Allowed memory size exhausted。臨時解決方式sudo -u www-data COMPOSER_MEMORY_LIMIT-1 composer install --no-dev --optimize-autoloader-1表示不限制內(nèi)存。但如果項目依賴很重建議還是給服務器加內(nèi)存或者開啟 Swap否則 composer 裝一半崩了后面全是麻煩。git pull時提示要輸入密碼說明服務器上這個倉庫是用 HTTPS 協(xié)議克隆的。改成 SSH 方式先在服務器上生成 SSH 密鑰并添加到 Gitee然后sudo -u www-data git remote set-url origin gitgitee.com:你的用戶名/你的倉庫名.git sudo -u www-data git pull origin main改一次之后后續(xù) pull 就不用輸密碼了。頁面報 500但storage/logs/laravel.log里沒有內(nèi)容有一種情況很隱蔽storage目錄權(quán)限是www-data但你執(zhí)行php artisan命令時用的用戶是 root導致storage/logs/laravel.log的屬主被 root 占用PHP 寫不進去日志文件里自然啥也沒有。排查時先看文件屬主ls -la /var/www/你的倉庫名/storage/logs/ sudo chown -R www-data:www-data /var/www/你的倉庫名/storage sudo -u www-data php artisan config:clear6.3 部署后頁面異常的排查速查表我把部署后最常見的幾種異?，F(xiàn)象整理成一張表你可以對照排查現(xiàn)象可能原因排查方向首頁直接顯示 500 或白屏storage 不可寫、vendor 缺失、.env 未配置查看storage/logs/laravel.log確認目錄權(quán)限子路由全部 404首頁正常Nginx 沒有配偽靜態(tài)檢查try_files配置reload Nginx頁面能打開但樣式和圖片全丟未執(zhí)行storage:link或站點根目錄不對確認 public 目錄配置執(zhí)行php artisan storage:link提示No application encryption keyAPP_KEY為空執(zhí)行php artisan key:generate數(shù)據(jù)庫連接失敗.env中數(shù)據(jù)庫配置錯誤或賬號權(quán)限不足核對 DB_HOST、DB_DATABASE、DB_USERNAME、DB_PASSWORD修改.env后配置不生效之前執(zhí)行過config:cache執(zhí)行php artisan config:clear再刷新訪問.env文件直接下載Nginx root 根目錄配錯確保 root 指向public目錄而不是項目根目錄排查 Laravel 頁面異常的通用套路是看日志sudo -u www-data tail -f /var/www/你的倉庫名/storage/logs/laravel.log日志里通常直接寫著異常原因比如某個擴展缺失、某個類找不到、數(shù)據(jù)庫連接失敗等。我處理部署問題時90% 的答案都在這一個文件里。剩下的 10%才是需要去檢查 Nginx 配置、PHP-FPM 狀態(tài)和系統(tǒng)權(quán)限。最后再分享一個我自己的習慣每次在大改之前先給當前能跑的配置做個備份。Nginx 配置在改之前復制成xxx.conf.bak.env在改之前也先備份一份。這套習慣讓我在維護多個 Laravel 項目時少踩了很多坑——版本回滾容易配置回滾有時候反而急得人直冒汗。部署這件事第一步走通之后后面就是重復和優(yōu)化但第一步走穩(wěn)了整條鏈路就順了。 Laravel項目部署：從Windows 10到Gitee再到服務器的完整鏈路
做 Laravel 項目最尷尬的一個時刻就是本地php artisan serve跑得好好的給同事演示也沒問題結(jié)果一到部署就卡住。代碼在 Windows 10 上寫好怎么弄到服務器上用 U 盤拷貝用壓縮包上傳再解壓這些辦法也不是不行但一旦項目要更新你就得重復上傳整個文件夾時間一長誰也受不了。更專業(yè)的做法是讓 Gitee 當中間人本地把代碼推送到 Gitee服務器再從 Gitee 拉取代碼并完成部署。這篇文章就圍繞這條鏈路把 Windows 10 開發(fā)環(huán)境、Laravel 框架、Gitee 倉庫、服務器部署這四件事串起來講清楚適合項目已經(jīng)在本地跑通、但第一次面對“上線”這個動作的開發(fā)者。這個流程遠沒有想象的復雜。本質(zhì)上就三步本地和 Gitee 建立信任關系把代碼推上去服務器和 Gitee 也建立信任關系把代碼拉下來最后在服務器上補齊依賴、配置環(huán)境并讓網(wǎng)站跑起來。真正容易出問題的是第一遍走流程時那些不起眼的細節(jié)。比如分支名對不上、.env被提交進倉庫、服務器上storage目錄權(quán)限不對、Nginx 偽靜態(tài)沒配導致路由 404。我會把每一步的操作命令、配置文件和踩坑點都寫出來你跟著走一遍基本能避開 90% 的部署問題。1. 項目拆解從 Windows 10 到服務器Laravel 項目的完整交付鏈路1.1 為什么用“本地推送、服務器拉取”這套鏈路很多第一次接觸部署的人會問為什么不能直接在服務器上開發(fā)或者為什么不用 FTP 上傳代碼答案很簡單——這兩條路對 Laravel 這種框架項目來說都不可持續(xù)。直接在服務器上開發(fā)等于放棄本地開發(fā)環(huán)境的各種便利。你在 Windows 10 上裝了 IDE、調(diào)試工具、瀏覽器擴展這些在服務器上統(tǒng)統(tǒng)沒有。而且服務器通常是 Linux 系統(tǒng)你還要額外熟悉一套環(huán)境效率很低。用 FTP 上傳則更危險因為 Laravel 項目里有大量文件手動上傳很容易漏文件、傳錯目錄。更重要的是FTP 無法保留版本歷史——你改壞了代碼想回滾到上一個能跑的版本FTP 做不到。而“本地推送 → Gitee 中轉(zhuǎn) → 服務器拉取”這套鏈路本質(zhì)上是把 Git 的版本管理能力延伸到了部署環(huán)節(jié)。本地提交一次Gitee 上就多一個歷史版本。服務器拉取一次線上代碼就對應一個明確的提交記錄。出了問題git log一看就知道線上跑的是哪個版本git checkout就能回到上一個穩(wěn)定版。這套流程對單人開發(fā)有效對團隊協(xié)作更是剛需——Gitee 上的代碼倉庫可以接入成員管理、代碼審查、Issue 跟蹤這些是 FTP 和 U 盤拷貝給不了的東西。1.2 鏈路中三個角色各自要做的事這條鏈路里一共有三個角色開發(fā)機、Gitee 倉庫、服務器。很多人對部署的理解是“把文件放到服務器上”其實更準確的說法是“讓三個角色之間形成一套標準流程”。角色扮演方核心任務開發(fā)機Windows 10編寫 Laravel 代碼、本地調(diào)試、提交代碼并推送到遠程倉庫遠程倉庫Gitee托管代碼、保存版本歷史、作為開發(fā)機與服務器之間的中轉(zhuǎn)分發(fā)點服務器Linux Nginx PHP-FPM MySQL拉取代碼、安裝依賴、配置環(huán)境變量、對外提供 Web 服務有一點要特別說明Laravel 項目部署比靜態(tài)網(wǎng)頁或普通 PHP 項目更繁瑣原因在于它有三個典型特征。第一它依賴 Composer 管理外部包代碼倉庫里通常不包含vendor目錄服務器拉下來之后必須先安裝依賴第二它依賴環(huán)境變量配置數(shù)據(jù)庫、緩存、應用密鑰等信息.env文件不能直接放進 Git 倉庫服務器上需要單獨創(chuàng)建第三它的入口文件在public目錄下Web 服務器的根目錄必須指向public還要配好偽靜態(tài)規(guī)則才能支持 Laravel 的路由系統(tǒng)。把這三點理解了后面的部署操作就有清晰的目標了。2. 本地準備Windows 10 下的 Git 安裝、SSH 密鑰與 Gitee 連接2.1 安裝 Git 并配置全局參數(shù)Windows 10 上第一步是安裝 Git。直接去 Git 官網(wǎng)下載 Windows 版本的安裝包安裝時一路默認即可。有幾個選項可以留意一下默認編輯器建議保留 Vim 或者改成 Notepad不影響后面操作PATH 環(huán)境變量選擇 “Git from the command line and also from 3rd-party software” 那一項換行符轉(zhuǎn)換建議選 “Checkout as-is, commit as-is”這個選擇能減少一部分換行符問題后面我會專門講 CRLF 的坑。安裝完 Git 之后打開 Git Bash先配置身份信息。這一步很重要因為 Git 的每一次提交都會把這兩個信息寫進提交記錄里。如果不配置提交時會報錯或者生成一串占位信息到后面看歷史記錄時非常難受。git config --global user.name 你的名字 git config --global user.email 你的郵箱example.com強烈建議這里的郵箱和你在 Gitee 注冊時用的郵箱保持一致。這樣你推送到 Gitee 的提交記錄能直接關聯(lián)到你的 Gitee 賬號團隊協(xié)作時能看清誰提交了什么。配置完成后可以用git config --list檢查一下確認兩個參數(shù)都寫進去了。2.2 生成 SSH 密鑰并把公鑰加到 GiteeWindows 10 下連接 Gitee 有兩種協(xié)議可選HTTPS 和 SSH。HTTPS 每次推送都要輸賬號密碼雖然 Git 可以緩存憑證但換機器、換用戶時經(jīng)常會遇到憑證沖突。SSH 則是一次配置永久免密并且安全性更高——它通過公鑰和私鑰配對的方式驗證你的身份私鑰保存在本地公鑰放在 Gitee。生成 SSH 密鑰的命令是在 Git Bash 里執(zhí)行ssh-keygen -t rsa -b 4096 -C 你的郵箱example.com執(zhí)行后會出現(xiàn)提示讓你選擇保存路徑直接回車用默認路徑即可。默認路徑是C:\Users\你的用戶名\.ssh\id_rsa.pub其中id_rsa是私鑰id_rsa.pub是公鑰。再次強調(diào)私鑰絕對不能泄露、不能上傳到任何地方公鑰可以分發(fā)到 Gitee 等平臺。接著查看公鑰內(nèi)容cat ~/.ssh/id_rsa.pub輸出結(jié)果是一長串以ssh-rsa開頭、以你的郵箱結(jié)尾的字符串。復制它然后打開 Gitee 網(wǎng)站登錄后進入 設置 → 安全設置 → SSH 公鑰把復制的內(nèi)容粘貼進去起一個容易辨識的標題比如“Windows10-dev”保存即可。2.3 驗證連接與常見失敗處理配置好公鑰后在 Git Bash 里執(zhí)行下面的命令驗證是否連通ssh -T gitgitee.com第一次執(zhí)行時系統(tǒng)會提示無法確認 host 身份問你是否繼續(xù)連接輸入yes回車。如果配置正確會看到類似這樣的輸出Hi 你的用戶名! Youve successfully authenticated, but GITEE.COM does not provide shell access.這句提示的意思是認證成功但 Gitee 不提供 shell 登錄能力這很正常說明 SSH 密鑰已經(jīng)生效。我遇到過不少次Permission denied (publickey)的情況排查順序一般是檢查公鑰是否完整復制到了 Gitee檢查本機 SSH key 是否存在ls -la ~/.ssh確認你當前用的賬號和 Gitee 上添加公鑰的賬號是同一個。還有一種容易被忽略的情況如果你之前用 HTTPS 方式克隆過倉庫Git 會優(yōu)先嘗試 HTTPS 認證這時需要檢查倉庫的 remote 地址是不是gitgitee.com開頭的 SSH 格式。3. 推送實戰(zhàn)創(chuàng)建 Gitee 倉庫、配置 .gitignore 并完成首次提交3.1 創(chuàng)建 Gitee 倉庫時的幾個關鍵選擇SSH 配置好之后下一步是去 Gitee 上創(chuàng)建一個空倉庫。進入 Gitee 首頁點“新建倉庫”會看到幾個需要填的選項。倉庫名稱最好和項目名一致比如laravel-blog方便識別。路徑會自動生成一般不用改?！笆欠耖_源”這個選項要慎重開源倉庫是所有人都能看到的私有倉庫只有你和被你添加的成員能訪問。如果你的項目里含業(yè)務敏感信息或者暫時不想公開就選“私有”。下面有個初始化倉庫的選項里面包含是否自動生成 README 文件。我個人建議先不要勾選自動生成 README也不要在 Gitee 上勾選添加 .gitignore 模板。理由很簡單——如果你在 Gitee 上初始化了倉庫本地第一次推送時就會出現(xiàn)“兩邊各自有獨立提交歷史”的沖突。后面對新手來說處理起來很麻煩還要先 pull 再 push。先創(chuàng)建空倉庫本地直接推是最順滑的路徑。還要留意一個設置Gitee 創(chuàng)建倉庫時可以選“分支模型”默認是master還是main不同版本界面可能不一樣記住你選的這個分支名。后面本地倉庫初始化的時候要把本地分支名改成和遠程一致否則推送時會提示分支不匹配。3.2 Laravel 項目的 .gitignore哪些文件絕對不能進倉庫Laravel 項目創(chuàng)建時根目錄下已經(jīng)自帶了一份.gitignore文件。這份文件的作用是告訴 Git某些目錄和文件不要納入版本控制。你可千萬別覺得沒必要這是 Laravel 項目部署中幾乎最重要的防線。至少要確認下面這些內(nèi)容在.gitignore里/vendorComposer 安裝的依賴包每個環(huán)境都可以單獨執(zhí)行composer install生成不需要、也不應該進倉庫node_modules同理前端依賴由npm install或yarn生成.env環(huán)境變量文件包含數(shù)據(jù)庫密碼、APP_KEY 等敏感信息絕不能進倉庫/storage/*.key存儲目錄下的密鑰文件storage/logs/*.log日志文件.idea、.vscodeIDE 的本地配置不同開發(fā)者配置不同不該提交.phpunit.result.cache測試緩存如果你發(fā)現(xiàn)vendor已經(jīng)被提交進了倉庫不要慌用下面的命令把它從 Git 管理中移除但保留本地文件git rm -r --cached vendor git commit -m chore: remove vendor directory from version control這里特別強調(diào).env的問題。我在現(xiàn)實中見過不止一次因為.env被誤提交導致數(shù)據(jù)庫密碼、郵箱密碼泄露甚至 APP_KEY 被公開后攻擊者可以利用 Laravel 的加密機制反序列化執(zhí)行惡意代碼。既然項目默認的.gitignore已經(jīng)把你保護好了就不要再自己去把.env手動git add進去。3.3 首次推送到遠程倉庫完整命令流代碼準備就緒后開始首次推送。打開 Git Bash進入你的 Laravel 項目根目錄依次執(zhí)行# 初始化本地倉庫 git init # 統(tǒng)一分支名假設遠程倉庫分支模型是 main git branch -M main # 把所有文件加入暫存區(qū) git add . # 提交 git commit -m feat: 初始化 Laravel 項目 # 關聯(lián)遠程倉庫換成你自己的倉庫地址 git remote add origin gitgitee.com:你的用戶名/你的倉庫名.git # 推送并建立上游跟蹤 git push -u origin main關于git branch -M main這一步多解釋一句。不同版本的 Git 默認分支名不一樣有的是master有的是main如果不統(tǒng)一推送時 Git 會提示fatal: The current branch master has no upstream branch或者遠程拒絕推送。先加這個參數(shù)保證本地分支和遠程倉庫分支一致后面就不糾結(jié)了。推送成功后打開 Gitee 倉庫頁面就能看到代碼了。-u參數(shù)的含義是“建立上游跟蹤”意思是把本地main分支和遠程main分支關聯(lián)起來之后你再執(zhí)行g(shù)it push或git pull就不用再帶倉庫地址和分支名了。如果第一次推送就被拒絕rejected大概率是遠程倉庫里已經(jīng)有提交記錄了。解決思路很簡單如果你確認遠程倉庫是空的或不該有的可以把遠程倉庫清掉重建如果遠程倉庫里確實有你需要的內(nèi)容比如同事推過代碼那就先拉取再合并git pull --rebase origin main git push -u origin main4. 服務器部署從 Gitee 拉取代碼到 Nginx 站點上線4.1 服務器環(huán)境準備LNMP 還是寶塔面板代碼推送到 Gitee 之后主角切換到服務器。服務器操作系統(tǒng)一般用 Linux常見的有 Ubuntu、Debian、CentOS。以 Ubuntu 22.04 為例Laravel 10 要求 PHP 版本不低于 8.1這里我裝 PHP 8.2 比較穩(wěn)妥。服務器環(huán)境的搭建有兩條路線手動搭建 LNMPLinux Nginx MySQL PHP或者用寶塔面板這類可視化工具。兩者各有優(yōu)劣。寶塔面板對新手極度友好圖形界面上點一點就能裝好 Nginx、PHP、MySQL還能創(chuàng)建站點、管理 SSL 證書。我自己的建議是著急上線、不想折騰環(huán)境的用寶塔想理解部署原理、以后好排查問題的手動搭建。不管用哪條路線最終服務器上要有的核心軟件是固定的NginxWeb 服務器負責接收 HTTP 請求、轉(zhuǎn)發(fā)給 PHP 處理PHP 8.x PHP-FPMPHP 解釋器和進程管理器MySQL / MariaDB數(shù)據(jù)庫ComposerPHP 依賴管理工具Git用于從 Gitee 拉取代碼Ubuntu 上手動安裝這些軟件包的命令大概是這樣sudo apt update sudo apt install -y nginx sudo apt install -y php8.2-fpm php8.2-cli php8.2-mysql php8.2-mbstring php8.2-xml php8.2-curl php8.2-zip php8.2-bcmath php8.2-gd sudo apt install -y composer sudo apt install -y git注意 PHP 擴展我寫了一個列表這些是 Laravel 正常運行必需的。漏裝php8.2-mbstring會導致使用字符串處理時報錯漏裝php8.2-xml會導致一些依賴包安裝失敗漏裝php8.2-zip會直接影響composer install的執(zhí)行。安裝完成后用php -v驗證版本用php -m列出已加載的擴展。4.2 在服務器上生成 SSH 密鑰并從 Gitee 拉取代碼服務器上的代碼來源有兩種方式SSH 方式和 HTTPS 方式。HTTPS 方式最簡單克隆無需額外配置但之后每次git pull都可能要求輸入賬號密碼或 Token。SSH 方式需要做一次密鑰配置但配好之后一勞永逸。服務器上生成 SSH 密鑰ssh-keygen -t rsa -b 4096 -C deployexample.com生成后查看公鑰cat ~/.ssh/id_rsa.pub把輸出的公鑰添加到 Gitee。這里有一個細節(jié)不建議把服務器公鑰加在“個人 SSH 公鑰”列表里更好的做法是使用 Gitee 的“部署公鑰”功能。部署公鑰可以綁定到指定倉庫而且可以只給只讀權(quán)限這樣即使服務器被入侵也只是能拉取這個倉庫的代碼不能往別的倉庫推送東西風險可控。配置完成后把代碼克隆到服務器。我習慣統(tǒng)一放在/var/www目錄下sudo mkdir -p /var/www cd /var/www sudo git clone gitgitee.com:你的用戶名/你的倉庫名.git克隆完成后你會看到/var/www/你的倉庫名這個目錄。這里要立刻處理目錄權(quán)限問題。PHP-FPM 默認以www-data用戶運行如果項目目錄的屬主是 rootPHP 就沒有權(quán)限寫日志、寫緩存。我通常的做法是把項目目錄的屬主改成www-datasudo chown -R www-data:www-data /var/www/你的倉庫名這一步看起來不起眼但如果不做后面 Laravel 報“Permission denied”會讓你排查很久。4.3 安裝依賴與環(huán)境配置composer install、.env 與 key:generate代碼拉下來之后第一件要做的事就是安裝 PHP 依賴。因為 Laravel 項目的vendor目錄默認不進 Git 倉庫服務器上執(zhí)行cd /var/www/你的倉庫名 sudo -u www-data composer install --no-dev --optimize-autoloader這是手動搭建環(huán)境時比較推薦的順序。--no-dev表示不安裝開發(fā)環(huán)境依賴線上環(huán)境用不到phpunit、barryvdh/laravel-debugbar之類的包裝上去只會拖慢應用、增加被攻擊面。--optimize-autoloader會生成優(yōu)化過的自動加載映射讓 Laravel 加載類更快一點。接下來創(chuàng)建環(huán)境變量文件。Laravel 默認提供.env.example作為模板直接復制sudo -u www-data cp .env.example .env然后編輯.env把關鍵配置改成線上環(huán)境對應的值APP_NAME你的應用名 APP_ENVproduction APP_DEBUGfalse APP_URLhttps://你的域名 DB_CONNECTIONmysql DB_HOST127.0.0.1 DB_PORT3306 DB_DATABASE你的數(shù)據(jù)庫名 DB_USERNAME你的數(shù)據(jù)庫用戶 DB_PASSWORD你的數(shù)據(jù)庫密碼這里有一個新手很容易忽略的點.env修改完之后必須執(zhí)行sudo -u www-data php artisan key:generate這個命令會生成一個隨機的 32 位字符串寫入.env的APP_KEY字段。Laravel 用它做加密解密、session 簽名、cookie 加密。如果APP_KEY為空頁面會直接報錯No application encryption key has been specified。在本地用php artisan serve時 Laravel 會自動處理但到服務器上手動部署這一步必須自己執(zhí)行。如果項目有數(shù)據(jù)庫遷移可以順便跑一下sudo -u www-data php artisan migrate --force--force參數(shù)是在生產(chǎn)環(huán)境跳過確認提示因為這里不帶APP_ENVproduction的話migrate 會停下來問“你確定要在生產(chǎn)環(huán)境執(zhí)行嗎”。還要建一個軟鏈接讓public/storage能訪問到storage/app/public目錄sudo -u www-data php artisan storage:link如果你用了 Laravel 的Storage磁盤功能上傳過文件這一步一定要做不然前端訪問上傳圖片會 404。關于權(quán)限我再補一條硬性要求sudo chmod -R 775 storage bootstrap/cachestorage目錄要寫日志、編譯 Blade 模板、存 session 和緩存bootstrap/cache要存配置文件緩存。如果這兩個目錄不可寫頁面會白屏或報 500。4.4 Nginx 站點配置根目錄、偽靜態(tài)與 PHP-FPMLaravel 項目跑起來需要 Nginx 把請求交給 PHP-FPM 處理。Nginx 的站點配置文件一般放在/etc/nginx/sites-available/下然后在/etc/nginx/sites-enabled/里建軟鏈接啟用。創(chuàng)建一個站點配置比如/etc/nginx/sites-available/laravelserver { listen 80; server_name your-domain.com; root /var/www/你的倉庫名/public; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php8.2-fpm.sock; } location ~ /\.(?!well-known).* { deny all; } }逐個說明幾個關鍵配置。root指向的是/var/www/你的倉庫名/public而不是項目根目錄。因為 Laravel 的入口文件是public/index.php所有 HTTP 請求都必須經(jīng)過這個入口處理。如果把 root 指到項目根目錄用戶訪問時會把.env、storage等敏感目錄直接暴露出來非常危險。try_files $uri $uri/ /index.php?$query_string;是 Laravel 路由的偽靜態(tài)規(guī)則。它的邏輯是先嘗試把請求作為真實文件返回找不到再當作目錄處理還找不到就全部交給index.php由 Laravel 的路由系統(tǒng)解析。沒有這一行你訪問/about這種路由時會直接 404因為服務器上根本沒有about這個文件。location ~ \.php$這一段把以.php結(jié)尾的請求交給 PHP-FPM 處理。這里fastcgi_pass用的是 Unix socket具體路徑要看你的 PHP 版本Ubuntu 上 PHP 8.2 對應/run/php/php8.2-fpm.sock。如果你用的不是 Ubuntu 或者 PHP 版本不同用php -v或systemctl status php8.2-fpm查一下路徑。配置文件寫好之后測試語法再重載sudo nginx -t sudo systemctl reload nginx到這里如果域名 DNS 解析已經(jīng)指向服務器打開瀏覽器訪問你的域名Laravel 網(wǎng)站應該就能正常顯示了。5. 上線優(yōu)化部署后的緩存刷新與日常更新流程5.1 上線前的幾個必要設置網(wǎng)站能打開只是第一步上線前還要做幾個優(yōu)化設置否則后面的維護會比較折騰。Laravel 提供了一組緩存命令把配置、路由、視圖編譯成緩存文件提高整體響應速度sudo -u www-data php artisan config:cache sudo -u www-data php artisan route:cache sudo -u www-data php artisan view:cacheconfig:cache會把所有配置文件合并成一個緩存文件Laravel 加載配置時就不需要逐個讀取.env和config目錄了。route:cache同樣會把路由表打包生產(chǎn)環(huán)境能明顯降低路由匹配耗時。需要提醒的是執(zhí)行了config:cache之后你再修改.env文件配置不會立即生效。此時要執(zhí)行php artisan config:clear才能重新讀取環(huán)境變量。這個特性很多新人不知道容易在改完數(shù)據(jù)庫密碼后得到一個“數(shù)據(jù)庫連接錯誤”的 500 頁面。再把.env里的APP_ENVproduction和APP_DEBUGfalse確認一遍。APP_DEBUGtrue時一旦發(fā)生異常Laravel 會把堆棧信息、環(huán)境變量、數(shù)據(jù)庫連接信息打印在頁面上。這在本地開發(fā)是神器在生產(chǎn)環(huán)境就是定時炸彈——任何一個報錯頁面都會把你的服務器底細暴露給訪問者。如果條件允許建議順手把 Nginx 的 80 端口重定向到 443HTTPS。證書可以用 Let’s Encrypt 免費申請配置好后在.env里把APP_URL改成https://開頭同時再執(zhí)行一次php artisan config:cache刷新配置。HTTPS 對加密 Cookie、登錄狀態(tài)保護都很重要這個不能省。5.2 日常更新流程拉取、裝依賴、刷新緩存服務器上的 Laravel 項目上線之后你還會持續(xù)提交代碼。日常發(fā)布更新的標準流程也應該形成固定套路。本地開發(fā)機上正常提交并推送git add . git commit -m feat: 增加某功能 git push origin main服務器上拉取最新代碼并部署cd /var/www/你的倉庫名 sudo -u www-data git pull origin main sudo -u www-data composer install --no-dev --optimize-autoloader sudo -u www-data php artisan migrate --force sudo -u www-data php artisan config:clear sudo -u www-data php artisan route:clear sudo -u www-data php artisan view:clear sudo -u www-data php artisan config:cache sudo -u www-data php artisan route:cache sudo -u www-data php artisan view:cache如果你沒有修改數(shù)據(jù)庫結(jié)構(gòu)migrate可以不執(zhí)行如果你更新的代碼沒有新增配置項config:clear和后面的config:cache也可以跳過。但我的習慣是每次都執(zhí)行一套完整的部署命令因為有些第三方擴展在安裝時會向config目錄發(fā)布配置文件不刷新緩存會導致新配置不生效。注意到我用sudo -u www-data執(zhí)行所有命令而不是直接用 root 或普通用戶。原因前面提過PHP-FPM 以www-data用戶運行用它執(zhí)行這些命令生成的文件屬主就是www-dataPHP 才有權(quán)限讀寫。如果用 root 執(zhí)行composer install生成的vendor屬主是 rootPHP 訪問不到頁面照樣報錯。這里說一句實在話更新時最怕的不是代碼寫錯而是更新流程不固定。每次更新都靠“手動拖文件”或者“只傳改過的那幾個文件”遲早會漏掉東西。把所有發(fā)布動作固定成上面這一串命令做成一個腳本或?qū)懗晒P記每次照做線上出問題就能快速定位是哪一步出了問題。6. 常見問題排查本地推送、服務器拉取與部署的坑6.1 本地到 Gitee 的典型問題推送時報Permission denied (publickey)這個提示說明 Git 沒有找到有效的 SSH 密鑰或者 Gitee 不認可你的公鑰。檢查順序是本地~/.ssh/id_rsa.pub是否存在Gitee 后臺是否添加了正確的公鑰執(zhí)行ssh -T gitgitee.com看報什么錯。如果提示Host key verification failed是因為服務器指紋未確認重連并輸入yes即可。報failed to push some refs遠程倉庫有本地沒有的提交記錄。最常見的原因就是你在創(chuàng)建 Gitee 倉庫時勾選了自動生成 README 或 .gitignore。解決方法是先拉取合并再推送git pull --rebase origin main git push -u origin main--rebase會把本地的提交“接”到遠程提交的后面保持線性歷史比直接默認合并更干凈。推送時出現(xiàn)LF will be replaced by CRLF警告這是 Windows 和 Linux 換行符差異導致的。Windows 用CRLF回車換行Linux 用LF換行。Git 默認在 Windows 上會把LF轉(zhuǎn)成CRLF這個警告大多數(shù)情況下無影響。但如果項目里有 Bash 腳本被轉(zhuǎn)換后上傳到 Linux 服務器執(zhí)行會報$\r: command not found這種錯誤。解決方式是在項目根目錄加一個.gitattributes文件* textauto eollf *.sh text eollf這樣 Git 會把文本文件統(tǒng)一按LF提交服務器拉取后就不會有\(zhòng)r的干擾。6.2 服務器上的典型問題composer install報內(nèi)存不足服務器內(nèi)存太小或者 PHP 的memory_limit太小Composer 在解析依賴時會報Allowed memory size exhausted。臨時解決方式sudo -u www-data COMPOSER_MEMORY_LIMIT-1 composer install --no-dev --optimize-autoloader-1表示不限制內(nèi)存。但如果項目依賴很重建議還是給服務器加內(nèi)存或者開啟 Swap否則 composer 裝一半崩了后面全是麻煩。git pull時提示要輸入密碼說明服務器上這個倉庫是用 HTTPS 協(xié)議克隆的。改成 SSH 方式先在服務器上生成 SSH 密鑰并添加到 Gitee然后sudo -u www-data git remote set-url origin gitgitee.com:你的用戶名/你的倉庫名.git sudo -u www-data git pull origin main改一次之后后續(xù) pull 就不用輸密碼了。頁面報 500但storage/logs/laravel.log里沒有內(nèi)容有一種情況很隱蔽storage目錄權(quán)限是www-data但你執(zhí)行php artisan命令時用的用戶是 root導致storage/logs/laravel.log的屬主被 root 占用PHP 寫不進去日志文件里自然啥也沒有。排查時先看文件屬主ls -la /var/www/你的倉庫名/storage/logs/ sudo chown -R www-data:www-data /var/www/你的倉庫名/storage sudo -u www-data php artisan config:clear6.3 部署后頁面異常的排查速查表我把部署后最常見的幾種異?，F(xiàn)象整理成一張表你可以對照排查現(xiàn)象可能原因排查方向首頁直接顯示 500 或白屏storage 不可寫、vendor 缺失、.env 未配置查看storage/logs/laravel.log確認目錄權(quán)限子路由全部 404首頁正常Nginx 沒有配偽靜態(tài)檢查try_files配置reload Nginx頁面能打開但樣式和圖片全丟未執(zhí)行storage:link或站點根目錄不對確認 public 目錄配置執(zhí)行php artisan storage:link提示No application encryption keyAPP_KEY為空執(zhí)行php artisan key:generate數(shù)據(jù)庫連接失敗.env中數(shù)據(jù)庫配置錯誤或賬號權(quán)限不足核對 DB_HOST、DB_DATABASE、DB_USERNAME、DB_PASSWORD修改.env后配置不生效之前執(zhí)行過config:cache執(zhí)行php artisan config:clear再刷新訪問.env文件直接下載Nginx root 根目錄配錯確保 root 指向public目錄而不是項目根目錄排查 Laravel 頁面異常的通用套路是看日志sudo -u www-data tail -f /var/www/你的倉庫名/storage/logs/laravel.log日志里通常直接寫著異常原因比如某個擴展缺失、某個類找不到、數(shù)據(jù)庫連接失敗等。我處理部署問題時90% 的答案都在這一個文件里。剩下的 10%才是需要去檢查 Nginx 配置、PHP-FPM 狀態(tài)和系統(tǒng)權(quán)限。最后再分享一個我自己的習慣每次在大改之前先給當前能跑的配置做個備份。Nginx 配置在改之前復制成xxx.conf.bak.env在改之前也先備份一份。這套習慣讓我在維護多個 Laravel 項目時少踩了很多坑——版本回滾容易配置回滾有時候反而急得人直冒汗。部署這件事第一步走通之后后面就是重復和優(yōu)化但第一步走穩(wěn)了整條鏈路就順了。