簡(jiǎn)介一份依托代碼托管平臺(tái)靜態(tài)頁(yè)功能的輕量級(jí)站點(diǎn)源碼包面向網(wǎng)頁(yè)前端和靜態(tài)博客初學(xué)者可幫助快速理解個(gè)人站點(diǎn)從內(nèi)容組織到發(fā)布上線的最小實(shí)現(xiàn)整體結(jié)構(gòu)非常精簡(jiǎn)。壓縮包共5個(gè)文件包括2個(gè)Markdown文檔、2個(gè)HTML頁(yè)面和1個(gè)YAML配置文件分別承擔(dān)內(nèi)容編寫(xiě)、頁(yè)面入口與站點(diǎn)全局配置整個(gè)包只有2KB。站點(diǎn)主題為「貓妖醬的乳首開(kāi)發(fā)日記」在個(gè)人主頁(yè)中展示了如何組織日記內(nèi)容、接入第三方搜索驗(yàn)證代碼并配置頁(yè)面元信息已有17319人瀏覽下載。通過(guò)分析這些源碼可快速了解個(gè)人靜態(tài)站點(diǎn)的目錄規(guī)范、頁(yè)面之間的鏈接方式以及驗(yàn)證文件與內(nèi)容文件的配合方法適合作為搭建個(gè)人日記或記錄類(lèi)站點(diǎn)的參考起點(diǎn)。 直接說(shuō)結(jié)論把一個(gè)個(gè)人項(xiàng)目放到 GitHub Pages 上并且綁定成github.io域名是目前成本最低、可控性最高的建站方式之一。站點(diǎn)本身就是靜態(tài)資源不需要服務(wù)器、不需要數(shù)據(jù)庫(kù)、不需要備案只要倉(cāng)庫(kù)在頁(yè)面就在。我給自己折騰過(guò)好幾個(gè)這樣的站點(diǎn)踩過(guò)的坑和摸出來(lái)的門(mén)道下面一次說(shuō)清楚。1. github.io 到底是什么以及它適合做什么1.1 它能干什么GitHub Pages 是 GitHub 提供的靜態(tài)站點(diǎn)托管服務(wù)每個(gè)賬號(hào)可以擁有一個(gè)username.github.io形式的專屬域名這個(gè)倉(cāng)庫(kù)名必須是username.github.io對(duì)應(yīng)的是該賬號(hào)的主站。除此之外每個(gè)普通倉(cāng)庫(kù)還可以開(kāi)啟 Pages 功能生成username.github.io/repo-name/這樣的項(xiàng)目子路徑頁(yè)面。這里說(shuō)的“靜態(tài)站點(diǎn)”意思是你的網(wǎng)站內(nèi)容在瀏覽器請(qǐng)求之前就已經(jīng)是完整的 HTML、CSS、JavaScript 文件了不需要后端程序動(dòng)態(tài)生成。好處非常直接訪問(wèn)速度快、安全性高、幾乎不用維護(hù)。對(duì)我來(lái)說(shuō)最實(shí)用的幾個(gè)用途包括技術(shù)博客、個(gè)人作品集、項(xiàng)目文檔、簡(jiǎn)歷頁(yè)面、工具聚合頁(yè)。如果你只是想展示自己做了什么、寫(xiě)過(guò)什么、能做什么github.io完全可以替代購(gòu)買(mǎi)云主機(jī) 域名 配置環(huán)境的整套流程。1.2 和“買(mǎi)服務(wù)器自建站”的區(qū)別很多人第一反應(yīng)是“我買(mǎi)臺(tái)服務(wù)器裝個(gè) Nginx部署個(gè) WordPress不也能建站嗎”但這兩者體驗(yàn)差異很大。對(duì)比項(xiàng)GitHub Pages自購(gòu)云服務(wù)器建站費(fèi)用免費(fèi)公開(kāi)倉(cāng)庫(kù)需要購(gòu)買(mǎi)服務(wù)器和域名維護(hù)無(wú)需操心需要安裝環(huán)境、打補(bǔ)丁、保證安全訪問(wèn)速度國(guó)內(nèi)訪問(wèn)一般可能需要 CDN 加速可以選國(guó)內(nèi)節(jié)點(diǎn)速度更快內(nèi)容生成純靜態(tài)文件支持動(dòng)態(tài)程序?qū)W習(xí)成本很低較高如果你需要的只是一個(gè)展示型或個(gè)人記錄型網(wǎng)站先別急著買(mǎi)服務(wù)器。GitHub Pages 完全夠用而且后期如果想遷移靜態(tài)文件去哪里都能部署不存在綁定關(guān)系。2. 從零開(kāi)始搭建一個(gè) github.io 頁(yè)面2.1 前置準(zhǔn)備你只需要三樣?xùn)|西一個(gè) GitHub 賬號(hào)、一個(gè)代碼編輯器VS Code 足夠、一個(gè)本地 Git 環(huán)境。如果還沒(méi)有安裝 Git去官網(wǎng)下載對(duì)應(yīng)系統(tǒng)的版本安裝后在終端執(zhí)行下面兩行設(shè)置好你的身份信息git config --global user.name 你的用戶名 git config --global user.email 你的郵箱這是 Git 提交代碼時(shí)用來(lái)標(biāo)記作者身份的不設(shè)置的話后面提交會(huì)報(bào)錯(cuò)或提示補(bǔ)全信息。2.2 創(chuàng)建專屬倉(cāng)庫(kù)登錄 GitHub 后點(diǎn)擊右上角加號(hào)選擇New repository。Repository name 那一欄必須填寫(xiě)你的用戶名.github.io。注意這一步是強(qiáng)約束只有完全匹配用戶名GitHub 才會(huì)把它識(shí)別為個(gè)人主頁(yè)倉(cāng)庫(kù)。如果填錯(cuò)后面即使部署成功訪問(wèn)地址也對(duì)不上。倉(cāng)庫(kù)權(quán)限保持默認(rèn)的 Public然后勾選Add a README file最后點(diǎn)擊創(chuàng)建。這個(gè)倉(cāng)庫(kù)創(chuàng)建好之后訪問(wèn)https://你的用戶名.github.io理論上你會(huì)看到 README 文件渲染出來(lái)的內(nèi)容。不過(guò)有時(shí)候因?yàn)榫彺婊蛘叱跏蓟瘯r(shí)間可能需要等幾分鐘才能看到。2.3 本地初始化項(xiàng)目把倉(cāng)庫(kù)克隆到本地開(kāi)始寫(xiě)你自己的頁(yè)面。git clone https://github.com/你的用戶名/你的用戶名.github.io.git cd 你的用戶名.github.io然后在項(xiàng)目根目錄創(chuàng)建一個(gè)index.html一個(gè)最簡(jiǎn)單的頁(yè)面長(zhǎng)這樣!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title我的個(gè)人主頁(yè)/title style body { font-family: system-ui, sans-serif; max-width: 720px; margin: 80px auto; padding: 0 24px; line-height: 1.8; color: #333; } /style /head body h1你好我是你的用戶名/h1 p這里是個(gè)人網(wǎng)站的首頁(yè)記錄我的項(xiàng)目與日常。/p /body /html保存后把這個(gè)文件提交并推送git add . git commit -m 初始化個(gè)人主頁(yè) git push origin main推送成功后再訪問(wèn)你的github.io地址就能看到自己寫(xiě)的頁(yè)面了。2.4 使用 Jekyll 快速搭建博客如果你不想從零寫(xiě) HTMLGitHub Pages 原生支持 Jekyll 靜態(tài)站點(diǎn)生成器。它的邏輯是你按照約定好的目錄結(jié)構(gòu)寫(xiě) Markdown 文章Jekyll 自動(dòng)生成完整的 HTML 站。最省事的方法不是本地安裝 Jekyll而是使用現(xiàn)成的主題倉(cāng)庫(kù)。在 GitHub 上搜索jekyll-theme挑一個(gè) star 數(shù)高的點(diǎn)擊Use this template以模板為起點(diǎn)創(chuàng)建你自己的倉(cāng)庫(kù)然后把倉(cāng)庫(kù)名改成你的用戶名.github.io。之后只需要修改_config.yml里的站點(diǎn)名稱、描述、個(gè)人鏈接等配置把_posts目錄下的示例文章刪掉換成你寫(xiě)的 Markdown 文件站點(diǎn)內(nèi)容就完全變成你自己的了。這里要特別注意_posts目錄里的文件命名格式必須是年-月-日-標(biāo)題.md這種格式例如2025-06-15-我的第一篇博客.md文件名里的日期會(huì)被當(dāng)作文章的發(fā)布日期不按這個(gè)格式命名Jekyll 不會(huì)識(shí)別成文章。3. 核心配置與部署細(xì)節(jié)3.1 倉(cāng)庫(kù)的 Settings 不是擺設(shè)推送完代碼之后很多人會(huì)在倉(cāng)庫(kù)的 Settings - Pages 里面看到一堆選項(xiàng)第一步要確認(rèn)Source選擇的是Deploy from a branch分支選擇main根目錄選/ (root)點(diǎn)擊 Save 保存。如果用的是 Jekyll 主題模板代碼推送到 main 分支之后GitHub Actions 會(huì)自動(dòng)觸發(fā)構(gòu)建流程。你可以到倉(cāng)庫(kù)的Actions選項(xiàng)卡里看構(gòu)建日志。第一次構(gòu)建可能需要一兩分鐘耐心等待即可。有一個(gè)比較隱蔽的點(diǎn)如果你的倉(cāng)庫(kù)之前被改名過(guò)或者從別的倉(cāng)庫(kù) fork 過(guò)來(lái)可能導(dǎo)致部署失敗。遇到這種情況最直接的排查方式是去 Actions 頁(yè)面看具體報(bào)錯(cuò)根據(jù)錯(cuò)誤信息調(diào)整而不是反復(fù)重新推送。3.2 自定義來(lái)源文件與項(xiàng)目子頁(yè)面如果你不只是做個(gè)人主頁(yè)還想為一個(gè)具體的項(xiàng)目單獨(dú)建文檔頁(yè)面可以在目標(biāo)項(xiàng)目的倉(cāng)庫(kù) Settings - Pages 中把Source設(shè)置為某個(gè)分支或者某個(gè)目錄。這里有個(gè)實(shí)際使用上的選擇建議對(duì)于純靜態(tài)項(xiàng)目直接把編譯產(chǎn)物放到gh-pages分支路徑指向 root對(duì)于和源碼混在一起的項(xiàng)目可以把產(chǎn)物放在docs目錄下Source 選擇main分支的/docs路徑。gh-pages分支是 GitHub Pages 的默認(rèn)約定分支很多自動(dòng)部署工具都認(rèn)它選它更通用。3.3 自定義域名與 HTTPSgithub.io自帶的域名已經(jīng)可以訪問(wèn)但如果你想用自己購(gòu)買(mǎi)的域名GitHub 也支持配置自定義域名。操作流程是先在購(gòu)買(mǎi)域名的服務(wù)商后臺(tái)添加一條 CNAME 解析記錄把www或者指向你的用戶名.github.io然后在倉(cāng)庫(kù) Settings - Pages 的Custom domain里填入你的域名點(diǎn) Save。GitHub 會(huì)自動(dòng)為這個(gè)域名申請(qǐng) HTTPS 證書(shū)不過(guò)證書(shū)簽發(fā)需要一些時(shí)間未生效之前不要關(guān)閉Enforce HTTPS選項(xiàng)。這里容易踩坑的地方是國(guó)內(nèi)某些域名服務(wù)商對(duì)根域名做 CNAME 解析可能不支持只支持 A 記錄。這種情況下你需要先去查詢你的用戶名.github.io映射到的 IP 地址然后把根域名用 A 記錄指向這些 IP。注意GitHub 的 IP 地址是有可能變化的官方會(huì)通過(guò)郵件通知變更所以有條件的話優(yōu)先使用支持 CNAME 的服務(wù)商。4. 實(shí)際維護(hù)中的常見(jiàn)問(wèn)題與排查方法4.1 訪問(wèn) github.io 出現(xiàn)樣式錯(cuò)亂這個(gè)問(wèn)題幾乎每個(gè)折騰過(guò)的人都遇過(guò)。樣式錯(cuò)亂的原因絕大多數(shù)是資源路徑寫(xiě)錯(cuò)了。GitHub Pages 的路徑分為兩種情況個(gè)人主頁(yè)username.github.io的根路徑是/而項(xiàng)目頁(yè)面的根路徑是/repo-name/。如果你的站點(diǎn)是項(xiàng)目頁(yè)面但是引用了/css/style.css這樣的絕對(duì)路徑瀏覽器會(huì)去username.github.io/css/style.css找文件結(jié)果自然是 404。解決方案有兩種一是把資源路徑全部改成相對(duì)路徑比如css/style.css或者./css/style.css二是在 HTML 里使用base標(biāo)簽配合一個(gè)在構(gòu)建時(shí)動(dòng)態(tài)生成的路徑變量。我的經(jīng)驗(yàn)是相對(duì)路徑最省心復(fù)制到任何環(huán)境下都不會(huì)因?yàn)橛蛎蚵窂阶兓鰡?wèn)題。4.2 文章更新了但頁(yè)面不顯示如果你使用 Jekyll文章文件、圖片、樣式都改完了推送后頁(yè)面卻沒(méi)有變化先用下面幾個(gè)思路排查檢查文件名是否符合YYYY-MM-DD-標(biāo)題.md格式檢查文件中是否正確配置了layout常用博客主題要求文章頭部有l(wèi)ayout: post看倉(cāng)庫(kù) Actions 的構(gòu)建日志是不是 Markdown 語(yǔ)法錯(cuò)誤導(dǎo)致構(gòu)建中斷瀏覽器強(qiáng)刷一次Mac 下 CmdShiftRWindows 下 CtrlF5排除本地緩存。有時(shí)候不是構(gòu)建失敗而是 GitHub 的 CDN 緩存還在舊版本這種情況等幾分鐘通常會(huì)恢復(fù)。4.3 關(guān)于 404 頁(yè)面GitHub Pages 很貼心地支持自定義 404 頁(yè)面。在倉(cāng)庫(kù)根目錄添加一個(gè)404.html訪問(wèn)不存在的地址時(shí)就會(huì)自動(dòng)展示這個(gè)頁(yè)面。我建議每個(gè)站點(diǎn)都配上一個(gè)既能提升體驗(yàn)也顯得專業(yè)。一個(gè)最普通的 404 頁(yè)面可以這樣寫(xiě)!DOCTYPE html html langzh-CN head meta charsetUTF-8 title頁(yè)面不存在/title /head body h1404/h1 p找不到這個(gè)頁(yè)面可能是地址寫(xiě)錯(cuò)了。/p pa href/回到首頁(yè)/a/p /body /html4.4 國(guó)內(nèi)訪問(wèn)速度優(yōu)化思路GitHub Pages 域名在國(guó)內(nèi)的訪問(wèn)穩(wěn)定性說(shuō)實(shí)話一般時(shí)快時(shí)慢高峰期偶爾還會(huì)加載不出來(lái)。這個(gè)問(wèn)題的根源在于 GitHub 的服務(wù)器不在國(guó)內(nèi)中間網(wǎng)絡(luò)鏈路不可控。在不動(dòng)服務(wù)器的情況下有幾種優(yōu)化手段可以使用如果只是個(gè)人使用可以考慮在瀏覽器端使用DevTools禁用緩存頻繁刷新頁(yè)面幫助判斷是否是網(wǎng)絡(luò)問(wèn)題如果站點(diǎn)以圖片等靜態(tài)資源為主可以把資源放到國(guó)內(nèi)訪問(wèn)更快的對(duì)象存儲(chǔ)服務(wù)比如阿里云 OSS然后在頁(yè)面里引用這些外鏈資源。不過(guò)需要注意GitHub Pages 本身不支持設(shè)置響應(yīng)頭也沒(méi)法通過(guò)代碼控制 CDN 緩存策略所以圖片塞在倉(cāng)庫(kù)里并不是一個(gè)非常理想的做法。另外有一個(gè)不算技巧的技巧盡量壓縮圖片和靜態(tài)資源體積減少請(qǐng)求數(shù)量這能讓頁(yè)面加載快不少。圖片壓縮工具網(wǎng)上有很多在線就行不必裝軟件。5. 把 github.io 玩出更多花樣5.1 用它做個(gè)人項(xiàng)目文檔站實(shí)際使用中g(shù)ithub.io除了做博客非常適合拿來(lái)搭項(xiàng)目文檔。很多開(kāi)源項(xiàng)目都把用戶手冊(cè)放在 GitHub Pages 上因?yàn)槲臋n和代碼保存在同一個(gè)倉(cāng)庫(kù)中更新文檔時(shí)直接改代碼倉(cāng)庫(kù)里的 Markdown 文件提交之后文檔站就自動(dòng)更新了流程非常順滑。我個(gè)人的做法是把文檔站的部署和主項(xiàng)目分開(kāi)管理主代碼倉(cāng)庫(kù)里只放源碼和docs目錄Pages 指向 docs同時(shí)在新版本 release 發(fā)布時(shí)自動(dòng)觸發(fā)一個(gè)構(gòu)建流程把生成的靜態(tài)文檔推到gh-pages分支。這樣源碼、文檔、發(fā)布物三者都不互相干擾維護(hù)起來(lái)很清爽。5.2 利用 GitHub Actions 實(shí)現(xiàn)自動(dòng)更新如果你不想每次手動(dòng)構(gòu)建、推送可以寫(xiě)一個(gè)簡(jiǎn)單的 GitHub Actions 工作流。工作流文件放在.github/workflows/main.yml核心邏輯是每當(dāng) main 分支有新的代碼推送時(shí)自動(dòng)安裝依賴、構(gòu)建項(xiàng)目、把產(chǎn)物部署到 Pages 分支。因?yàn)槲仪岸隧?xiàng)目比較常用的構(gòu)建工具是 Vite一個(gè)精簡(jiǎn)版的部署工作流大概長(zhǎng)這樣name: Deploy to GitHub Pages on: push: branches: [main] permissions: contents: write jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install and Build run: | npm install npm run build - name: Deploy uses: peaceiris/actions-gh-pagesv4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist這個(gè)配置文件寫(xiě)好后后續(xù)只要推代碼站點(diǎn)就會(huì)自動(dòng)重新部署全程不用登錄服務(wù)器、不用手動(dòng)執(zhí)行構(gòu)建命令體驗(yàn)非常舒服。5.3 結(jié)合自己的需求做內(nèi)容規(guī)劃回到一開(kāi)始說(shuō)的場(chǎng)景一個(gè)個(gè)人站點(diǎn)想清楚“放什么”比“怎么搭”更重要。我的建議是把站點(diǎn)規(guī)劃成三個(gè)核心板塊作品展示區(qū)、日志記錄區(qū)、資源聚合區(qū)。作品展示區(qū)放你做過(guò)的項(xiàng)目或案例配上鏈接和圖片日志記錄區(qū)寫(xiě)踩坑經(jīng)驗(yàn)、學(xué)習(xí)記錄資源聚合區(qū)放工具、書(shū)單、推薦鏈接。內(nèi)容不需要一開(kāi)始就填滿先把框架搭出來(lái)后續(xù)慢慢補(bǔ)充。對(duì)一個(gè)長(zhǎng)期維護(hù)的個(gè)人站點(diǎn)來(lái)說(shuō)持續(xù)輸出比一次性寫(xiě)完更重要。6. 踩坑實(shí)錄與經(jīng)驗(yàn)補(bǔ)充6.1 文件名大小寫(xiě)問(wèn)題GitHub Pages 是部署在 Linux 環(huán)境上的文件系統(tǒng)區(qū)分大小寫(xiě)。如果你在本地 Windows 或 Mac 上開(kāi)發(fā)時(shí)引用了Image.jpg但文件實(shí)際名稱是image.jpg本地預(yù)覽可能正常部署到線上就會(huì)出現(xiàn)圖片加載失敗。這個(gè)坑很隱蔽因?yàn)楸镜亻_(kāi)發(fā)服務(wù)器一般不區(qū)分大小寫(xiě)。遇到圖片或資源 404第一反應(yīng)應(yīng)該是檢查文件名的大小寫(xiě)是否完全一致。6.2 push 之后等不到更新有時(shí)候你推送了代碼刷新頁(yè)面還是老樣子。排除緩存問(wèn)題后大概率是構(gòu)建流程還沒(méi)結(jié)束。GitHub Pages 的構(gòu)建雖然不是秒級(jí)完成但通常也就一兩分鐘。你可以在倉(cāng)庫(kù)的 Actions 頁(yè)面看進(jìn)度如果構(gòu)建失敗頁(yè)面上會(huì)直接顯示紅色錯(cuò)誤。還有一個(gè)比較容易忽略的點(diǎn)如果你使用的是自定義 GitHub Actions 部署流程記得在倉(cāng)庫(kù) Settings - Actions - General - Workflow permissions 中把權(quán)限設(shè)為Read and write permissions否則推送構(gòu)建產(chǎn)物到 gh-pages 分支時(shí)會(huì)報(bào)權(quán)限錯(cuò)誤。6.3 不要把秘密文件提交進(jìn)倉(cāng)庫(kù)因?yàn)槭枪_(kāi)倉(cāng)庫(kù)你的 GitHub Pages 站點(diǎn)本身就是公開(kāi)的。任何提交到倉(cāng)庫(kù)的內(nèi)容都會(huì)直接暴露在互聯(lián)網(wǎng)上。代碼中的 API Key、數(shù)據(jù)庫(kù)連接串、個(gè)人敏感信息絕對(duì)不要提交進(jìn)去。我見(jiàn)過(guò)不少人在早期項(xiàng)目里把環(huán)境變量硬編碼在代碼里結(jié)果部署后直接被搜索引擎抓走非常被動(dòng)。正確的做法是敏感信息放在 GitHub Secrets 中構(gòu)建時(shí)通過(guò)環(huán)境變量注入或者本地配置文件加入.gitignore強(qiáng)制不納入版本管理。7. 寫(xiě)在最后的個(gè)人體會(huì)我前前后后用 GitHub Pages 搭過(guò)不同類(lèi)型的站點(diǎn)有純手工寫(xiě) HTML 的個(gè)人主頁(yè)有基于 Jekyll 的博客有用 Vite 構(gòu)建后自動(dòng)部署的前端項(xiàng)目文檔站。每個(gè)項(xiàng)目的規(guī)模和復(fù)雜度不同但核心邏輯一直沒(méi)變過(guò)內(nèi)容以靜態(tài)文件形式存在代碼倉(cāng)庫(kù)就是發(fā)布中心推送即部署。這套模式非常適合個(gè)人項(xiàng)目和中小型團(tuán)隊(duì)使用不花一分錢(qián)就能擁有一個(gè)可以長(zhǎng)期維護(hù)、隨時(shí)遷移的站點(diǎn)。如果你之前一直只想不做建議今天就去建一個(gè)倉(cāng)庫(kù)放上一個(gè)最簡(jiǎn)單的index.html先把跑起來(lái)的感覺(jué)找到再慢慢把內(nèi)容和結(jié)構(gòu)填起來(lái)。真到上手之后你會(huì)發(fā)現(xiàn)最難的部分其實(shí)不是技術(shù)而是想清楚你要寫(xiě)什么。本文還有配套的精品資源點(diǎn)擊獲取