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