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