# GitHub Pages: lưu trữ website miễn phí, cách xuất bản từng bước

URL: https://skillaria.top/vi/guides/git/github-pages-dang-website-mien-phi

GitHub Pages là dịch vụ lưu trữ website tĩnh miễn phí, chạy trực tiếp từ repository GitHub. Bạn đặt file HTML, CSS và JavaScript vào repository, bật Pages trong cài đặt, và website mở tại địa chỉ dạng username.github.io. Có thể dùng tên miền và HTTPS riêng, nhưng mã phía máy chủ như PHP và cơ sở dữ liệu không được hỗ trợ.

## GitHub Pages là gì

GitHub Pages là dịch vụ lưu trữ website tĩnh miễn phí, tích hợp sẵn trong GitHub. Bạn lưu file website trong một repository Git thông thường, và GitHub phục vụ chúng qua HTTPS. Mỗi lần `git push` lên nhánh được chọn sẽ cập nhật website, nên bạn không cần FTP, bảng điều khiển hosting hay tải file thủ công.

Trong các công cụ tìm kiếm tiếng Việt, dịch vụ này được gọi bằng nhiều cách: "github pages", "github pages miễn phí", hoặc "hosting github". Cũng có người hỏi "git pages là gì", nhưng tên đúng là GitHub Pages: đây là tính năng của nền tảng GitHub, không phải của Git. Bản thân Git không xuất bản gì cả; nó chỉ lưu lịch sử thay đổi.

Những thứ thường được đưa lên GitHub Pages là tài liệu dự án, trang cá nhân và portfolio, blog, landing page, các dự án học tập, và bản demo ứng dụng frontend viết bằng React, Vue hoặc Svelte sau khi đã build.

### Git pages là hosting cho nội dung tĩnh

Từ khóa quan trọng là tĩnh. GitHub Pages chỉ gửi cho trình duyệt các file đã sẵn sàng: HTML, CSS, JavaScript, hình ảnh, font, JSON. Máy chủ không chạy bất kỳ mã nào: PHP, Python, Node.js phía máy chủ và cơ sở dữ liệu đều không hoạt động ở đây. Nếu website cần đăng ký, giỏ hàng, hay trang quản trị với cơ sở dữ liệu, bạn cần hosting thông thường hoặc nền tảng cloud.

JavaScript chạy trong trình duyệt vẫn hoạt động bình thường. Ứng dụng một trang có thể gọi API bên ngoài, biểu mẫu có thể gửi qua dịch vụ của bên thứ ba, và tìm kiếm trên website có thể làm ngay phía client.

## Các loại website trên GitHub Pages

GitHub Pages có ba loại website, và loại quyết định địa chỉ.

| Loại | Repository | Địa chỉ |
| --- | --- | --- |

| Website người dùng | `username.github.io` | `https://username.github.io/` |

| Website tổ chức | `orgname.github.io` | `https://orgname.github.io/` |

| Website dự án | tên tùy chọn, ví dụ `docs` | `https://username.github.io/docs/` |

Mỗi tài khoản chỉ có một website người dùng hoặc tổ chức, còn website dự án thì có thể có nhiều, mỗi repository một website. Tên repository cho website cá nhân phải trùng khớp với username GitHub của bạn: nếu username là `ivan-petrov` thì repository phải tên `ivan-petrov.github.io`.

Với repository công khai, Pages có sẵn trong gói miễn phí. Xuất bản website từ repository riêng tư cần gói trả phí của GitHub; còn website đã xuất bản vẫn có thể được mọi người trên internet truy cập.

## Cách xuất bản website trên GitHub Pages từng bước

Chúng ta đi theo cách đơn giản nhất: các file HTML đã sẵn sàng, xuất bản từ một nhánh. Bạn cần tài khoản GitHub và Git đã được cài.

### Bước 1. Tạo repository

Trên GitHub, tạo một repository công khai mới. Với website cá nhân, đặt tên `username.github.io`; với website dự án, đặt tên tùy ý. Sau đó clone và thêm trang chính:

```
git clone https://github.com/username/username.github.io.git
cd username.github.io
echo "

# Xin chào, GitHub Pages

" > index.html
```

Trang chính bắt buộc phải tên là `index.html` (hoặc `index.md`, hoặc `README.md`; GitHub cũng sẽ biến chúng thành trang chính). Phân biệt chữ hoa, chữ thường: `Index.html` sẽ không được nhận.

### Bước 2. Đưa file lên GitHub

```
git add index.html
git commit -m "Trang đầu tiên của website"
git push origin main
```

Nếu lần đầu gửi lên mà Git hỏi tên đăng nhập và mật khẩu, hãy dùng personal access token hoặc đăng nhập qua trình duyệt. Mật khẩu tài khoản GitHub thông thường không được chấp nhận cho `git push` qua HTTPS.

### Bước 3. Bật Pages trong cài đặt

Mở repository trên GitHub, vào Settings, rồi chọn Pages ở menu bên trái. Trong khối Build and deployment, tại ô Source, chọn Deploy from a branch. Bên dưới, chọn nhánh (thường là `main`) và thư mục: gốc `/ (root)` hoặc `/docs`. Nhấn Save.

Thư mục `/docs` tiện khi repository chứa mã nguồn dự án, còn website tài liệu nằm riêng trong một thư mục khác.

### Bước 4. Chờ website được xuất bản

Việc xuất bản mất từ vài giây đến vài phút. GitHub cảnh báo lần đầu có thể mất tới 10 phút. Tiến trình build xem được ở tab Actions, nơi xuất hiện quy trình pages build and deployment. Khi xong với dấu tích xanh, địa chỉ website sẽ hiện ở Settings → Pages.

Từ đó trở đi, bạn chỉ cần sửa file, commit và `git push` là website tự cập nhật.

## Xuất bản bằng GitHub Actions

Xuất bản từ nhánh phù hợp khi repository đã có sẵn file để phục vụ. Nếu website cần được build trước, chẳng hạn ứng dụng Vite, React, hoặc bộ sinh trang như Hugo, hãy dùng nguồn GitHub Actions. Trong Settings → Pages, tại ô Source, chọn GitHub Actions, và GitHub sẽ đề xuất các mẫu workflow có sẵn.

Một workflow tối giản để đưa các file tĩnh trong thư mục `dist` sau khi build trông như sau:

```
name: Deploy to Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4
```

File này nằm ở `.github/workflows/pages.yml`. Sau `git push`, Actions sẽ cài các phụ thuộc, build dự án, rồi đưa nội dung `dist` lên. Ưu điểm là repository chỉ chứa mã nguồn, còn các file đã build không làm rối lịch sử commit.

Cái bẫy thường gặp với website dự án là đường dẫn. Website mở ở địa chỉ `/tên-repository/`, nhưng bộ build thường tham chiếu tài nguyên từ gốc `/`. Kết quả là trang tải không có kiểu dáng và script. Cách sửa là đặt base path: trong Vite dùng tham số `base: '/tên-repository/'`, và với bộ build khác dùng tùy chọn tương tự.

## Jekyll và các bộ sinh website tĩnh

Khi xuất bản từ nhánh, GitHub mặc định xử lý file bằng Jekyll, bộ sinh website tĩnh viết bằng Ruby. Nhờ vậy bạn có thể viết trang bằng Markdown, dùng theme và template, và GitHub sẽ chuyển thành HTML. Với blog hoặc tài liệu, cách này rất tiện: bạn viết file `.md`, còn giao diện lấy từ theme.

Hệ quả là Jekyll bỏ qua các file và thư mục có tên bắt đầu bằng dấu gạch dưới, ví dụ `_next` hoặc `_assets`. Nếu website được build bằng công cụ khác và cần các thư mục như vậy, hãy đặt một file rỗng tên `.nojekyll` ở gốc:

```
touch .nojekyll
git add .nojekyll
git commit -m "Tắt Jekyll"
git push
```

Các bộ sinh khác như Hugo, Astro, Eleventy, MkDocs, Docusaurus chạy qua GitHub Actions: build trong workflow, rồi xuất bản thư mục kết quả. Bản thân GitHub Pages không biết gì về chúng và chỉ cần file cuối cùng.

## Cách gắn tên miền riêng vào GitHub Pages

Địa chỉ `username.github.io` phù hợp với dự án học tập, nhưng với portfolio hay dự án, nên dùng tên miền riêng. Việc kết nối được làm ở hai nơi: nhà đăng ký tên miền và cài đặt repository.

### Cấu hình DNS

Với tên miền con như `www.example.com` hoặc `blog.example.com`, tạo bản ghi CNAME trỏ về `username.github.io`. Với tên miền gốc `example.com`, tạo bản ghi A tới các địa chỉ IP của GitHub Pages:

```
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
```

Danh sách địa chỉ mới nhất, kể cả IPv6 cho bản ghi AAAA, có trong tài liệu của GitHub; hãy đối chiếu trước khi cấu hình. Nên thiết lập cả tên miền gốc lẫn `www`, để GitHub chuyển hướng một địa chỉ sang địa chỉ kia.

### Cấu hình trong repository

Trong Settings → Pages, điền tên miền vào ô Custom domain rồi lưu. Khi xuất bản từ nhánh, GitHub sẽ tạo file `CNAME` trong repository chứa tên miền. Nếu xuất bản qua Actions, không cần file `CNAME`, vì tên miền được lưu trong cài đặt.

GitHub khuyên bạn nên xác minh tên miền trong cài đặt tài khoản (mục Pages trong cài đặt hồ sơ). Điều này ngăn người khác gắn tên miền của bạn vào repository của họ khi DNS vẫn trỏ về GitHub. Thay đổi DNS có thể mất đến một ngày, nên nếu tên miền chưa hoạt động ngay, hãy đợi thêm.

## HTTPS trên GitHub Pages

Với địa chỉ `*.github.io`, HTTPS luôn được bật. Với tên miền riêng, GitHub tự cấp chứng chỉ Let's Encrypt khi DNS đã được cấu hình đúng. Sau đó, trong Settings → Pages sẽ xuất hiện ô Enforce HTTPS. Hãy bật ô này để mọi yêu cầu HTTP được chuyển sang HTTPS.

Nếu ô không khả dụng, nghĩa là chứng chỉ chưa được cấp: kiểm tra bản ghi DNS và chờ thêm. Đôi khi giúp ích khi xóa tên miền khỏi ô Custom domain rồi thêm lại, để GitHub cấp chứng chỉ một lần nữa. Ngoài ra, hãy kiểm tra website không tải hình ảnh hay script qua `http://`, vì trình duyệt sẽ chặn các tài nguyên đó như nội dung hỗn hợp (mixed content).

## Giới hạn của GitHub Pages

Dịch vụ này miễn phí nhưng có giới hạn. Các giới hạn được ghi trong tài liệu GitHub, và với hầu hết website cá nhân hay học tập thì con số đó là quá đủ.

| Giới hạn | Giá trị |
| --- | --- |

| Nội dung | chỉ file tĩnh, không có mã phía máy chủ và cơ sở dữ liệu |

| Kích thước website đã xuất bản | tối đa 1 GB |

| Kích thước repository khuyến nghị | tối đa 1 GB |

| Băng thông | giới hạn mềm 100 GB mỗi tháng |

| Build từ nhánh | giới hạn mềm 10 lần mỗi giờ (không áp dụng cho Actions) |

| Thời gian xuất bản | quá 10 phút thì bị dừng |

Ngoài giới hạn kỹ thuật, còn có điều khoản sử dụng: GitHub Pages không dành cho dịch vụ thương mại như cửa hàng trực tuyến hay SaaS, và không dùng để chia sẻ file dung lượng lớn. Với portfolio, tài liệu, blog và landing page của dự án thì hoàn toàn phù hợp.

Một giới hạn khác là không có cấu hình máy chủ. Không có chuyển hướng tùy chỉnh, không có header phản hồi riêng, và không có quy tắc kiểu `.htaccess`. Bạn chỉ có thể đặt trang `404.html` ở gốc; GitHub sẽ hiển thị trang này cho các địa chỉ không tồn tại.

## Các vấn đề thường gặp và cách xử lý

### Lỗi 404 trên GitHub Pages

Nguyên nhân phổ biến nhất là không có file `index.html` trong thư mục được chọn làm nguồn. Kiểm tra đã chọn đúng nhánh và thư mục (`/ (root)` hoặc `/docs`), và file tên chính xác là `index.html` viết thường. Nguyên nhân thứ hai: website chưa được xuất bản. Hãy xem tab Actions và chờ build hoàn tất.

Nếu lỗi 404 xuất hiện ở các trang bên trong của ứng dụng một trang khi tải lại, vấn đề nằm ở định tuyến: máy chủ không biết địa chỉ `/about` vì không có file tương ứng. Cách khắc phục là dùng hash routing (`/#/about`) hoặc tạo bản sao `index.html` với tên `404.html`.

### Website không được cập nhật

Trước hết, đảm bảo thay đổi đã thật sự lên GitHub: chạy `git status` và `git log origin/main --oneline -3`. Sau đó mở tab Actions. Nếu build thất bại, sẽ có dấu X đỏ và nhật ký lỗi, ví dụ cú pháp sai trong file Jekyll hoặc lỗi trong workflow.

Nếu build thành công nhưng trình duyệt vẫn hiện phiên bản cũ, nguyên nhân là bộ nhớ đệm. GitHub Pages lưu cache file trong vài phút, và trình duyệt cũng lưu cache. Tải lại trang sau khi xóa cache (Ctrl+F5 hoặc Cmd+Shift+R), hoặc mở trong cửa sổ ẩn danh.

### Kiểu dáng và hình ảnh không tải

Hầu như luôn là do đường dẫn sai. Trên website dự án, liên kết `/style.css` trỏ về gốc của `username.github.io`, không phải thư mục của repository. Hãy dùng đường dẫn tương đối (`style.css`, `./img/logo.png`) hoặc đặt base path trong bộ build. Cũng kiểm tra chữ hoa, chữ thường trong tên file: máy chủ GitHub phân biệt `Logo.PNG` và `logo.png`, dù trên Windows khi chạy cục bộ mọi thứ vẫn bình thường.

### Thư mục có gạch dưới bị mất

Đây là việc của Jekyll: nó không xuất bản các thư mục như `_app`. Thêm file `.nojekyll` ở gốc, hoặc chuyển sang xuất bản bằng GitHub Actions.

## Kết luận

GitHub Pages là cách nhanh nhất để xuất bản website tĩnh miễn phí: một repository, file `index.html`, nguồn trong Settings → Pages, và trong vài phút website đã mở tại `username.github.io`. Với website cần build, hãy dùng GitHub Actions. Với tên miền riêng, hãy cấu hình bản ghi DNS và bật Enforce HTTPS. Đừng quên giới hạn: chỉ nội dung tĩnh, không có mã máy chủ, và có trần về dung lượng cùng băng thông. Làm việc với GitHub, gửi thay đổi và tự động hóa việc xuất bản được trình bày thực hành trong khóa học Git.

## FAQ

**GitHub Pages có thật sự miễn phí không?**

Có, với repository công khai trong gói miễn phí, GitHub Pages không tính phí, kể cả HTTPS và tên miền riêng. Bạn chỉ trả tiền cho tên miền ở nhà đăng ký, và cho gói GitHub trả phí nếu muốn xuất bản từ repository riêng tư.

**Có thể dùng GitHub Pages cho website PHP hoặc WordPress không?**

Không. GitHub Pages chỉ phục vụ file tĩnh và không chạy mã phía máy chủ. Website WordPress có thể xuất thành HTML tĩnh bằng một số plugin, nhưng biểu mẫu, bình luận và trang quản trị sẽ không hoạt động.

**Có thể tạo bao nhiêu website trên GitHub Pages?**

Một website người dùng tại username.github.io và không giới hạn số website dự án, mỗi website ứng với một repository.

**Các công cụ tìm kiếm có lập chỉ mục website GitHub Pages không?**

Có, các website này được lập chỉ mục như website thông thường. Để lập chỉ mục tốt hơn, hãy thêm sitemap.xml và robots.txt ở gốc, rồi xác minh website trong công cụ dành cho quản trị web của các công cụ tìm kiếm.

**Làm thế nào để gỡ website khỏi GitHub Pages?**

Trong Settings → Pages, nhấn Unpublish site nếu nút này có sẵn, hoặc chọn None ở ô Source. Xóa repository cũng sẽ xóa website.


---
Source: Skillaria.Top (https://skillaria.top)