如何搭建免费的在线项目主页？

开源项目

开源项目有了，项目介绍主页得有吧？

文档需求

随之而来的是另外几个问题：

1. 如何在线演示demo?
2. 如何全网介绍项目？
3. 如何做项目管理？

常见问题

拓展问题：

1. 日常想搭建自有博客？
2. 想部署一个静态网站？（不办理各种手续～懂得都懂）
3. 每一个项目都想做一个介绍站点？
4. 想部署 Spa 应用？如 Vue React

解决办法

通过github可以实现上述需求， github 官方中文说明 可以根据文档满足自己的需求

方式一：仓库新建 gh-pages 分支，部署到github pages 作为项目主页（gitee同理）和在线demo

方式二：直接在项目里创建 wiki 作为项目文档说明

方式三：使用国内文档（语雀、飞书、腾讯文档等...github 国内访问不稳定，速度慢～）

其他方案

可以通过开源博客（可选模板）/ 文档工具实现

1. hugo 博客
2. jekyllrb 博客
3. hexo 博客
4. dumi 文档工具
5. vitepress 文档工具

构建开源电子书：gitbook

编写、生成、发布一本在线图书，也能导出多种文件格式

详细步骤

这里详细介绍如何用 github pages 功能 。官方文档 ： 查看

查看github pages 示例 查看

1.创建仓库

2.创建分支

分支名必须是 gh-pages

3.启用 Github Pages服务

github pages 设置选项，将分支选择为 gh-pages，选择 root 根目录

4.添加网站内容

将要发布的网站内容（HTML、CSS、JS以及其他静态资源）放在gh-pages分支的根目录下，接着使用以下命令将其上传到远程仓库

git push origin gh-pages

或者运行

npm run deploy 自动打包并上传分支gh-pages

配置项目 package.json 文件， 新增 deploy 脚本

"scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "deploy": "npm run build && gh-pages -d dist"
  }

5.访问地址

URL规则： 如 username: winyh , repository: winsax

静态网站：[https://<username>.github.io/] winyh.github.io

项目主页：http(s)://<username>.github.io/<repository> winyh.github.io/winsax

也可以加项目打包文件目录，如winyh.github.io/winsax/dist，会自动访问dist下的index.html

如果做静态网站，仓库名一定要填 <username>.github.io 的格式, 如 winyh.github.io

自定义域名

你可以为你的gh-pages网站绑定自己的域名，只需要在仓库的根目录下添加CNAME文件，内容为你的域名，然后在域名管理平台中添加一条CNAME记录，将其指向Github的服务器即可。

取消/重新发布站点

取消发布站点时，当前部署将被删除，并且该站点将不再可用

自动化部署

项目主页有了， 自动化部署也得有，凡是需要重复花时间的都可以抽象或者借助工具～

通过 github actions 自动化部署

1.新建yml脚本

在项目的根目录下创建 .github/workflows/xxx.yml 如 deploy / docs / pages

这两个 .github/workflows 目录的名字不能修改，xxx.yml 文件则可以任意写（后缀只能为yml）

示例

name: winsax actions
run-name: ${{ github.actor }} 创建自动化执行 🚀
on: [push]

# on:
#   push:
#     branches:
#       - main # default branch
#   pull_request:
#     branches:
#       - main # default branch

jobs:
  Winsax-Deploy-Actions:
    runs-on: ubuntu-latest
    steps:
      - run: echo "🎉 流程通过 ${{ github.event_name }} 执行."
      - run: echo "🎄 任务流运行在 ${{ runner.os }} GitHub 提供的主机!"
      - run: echo "🚀 当前分支为 ${{ github.ref }} ，当前仓库为 ${{ github.repository }}."
      # 将代码仓库的内容检出工作目录中，待以下工作流中使用
      - name: Check out repository code
        uses: actions/checkout@v4
      - run: echo "📮 仓库 ${{ github.repository }} 已检出到 GitHub 服务器工作目录."
      - run: echo "🔱 即将在GitHub服务器执行工作流."
      # 设置 node 环境版本
      - name: Set node version
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      # 安装 npm 依赖
      - name: Install node modules
        run: npm install
      # 缓存 node modules
      - name: Cache node modules
        uses: actions/cache@v4
        env:
          cache-name: cache-node-modules
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-
      # 列举仓库文件
      - name: List files in the repository
        run: |
          ls ${{ github.workspace }}
      # 构建项目
      - name: Build
        run: npm run build
      # 部署到gh-pages分支
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
          publish_branch: gh-pages # 将 dist 下面的产出推送到关联仓库的 gh-pages 分支，如果没有会自动创建
      # 发布版本
      - name: Create gitHub Release
        id: create_release
        uses: softprops/action-gh-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        if: startsWith(github.ref, 'refs/tags/')
        with:
          name: ${{ github.ref_name }} # 仓库页右侧 Release 名称
          tag_name: ${{ github.ref }}
          draft: false
          prerelease: false
          files: |
            Release.txt
            LICENSE
      - run: echo "🍏 当前任务流状态  ${{ job.status }}."

yml 文件关键字

on: 定义触发工作流的事件 [push, fork, pull_request , ...]。

jobs: 定义工作流中的任务。

Winsax-Deploy-Actions: 任务的名称，表示构建和部署。

runs-on: 指定任务运行的操作系统，这里是 ubuntu-latest。

steps: 定义任务的一系列步骤。

name: 步骤的名称。

uses: 使用的 GitHub Action。

with: 配置项，用于传递参数给 Action。

run: 执行的脚本命令。

以上部署脚本具体执行步骤如下:

详情图

踩坑指南

部署过程中遇到一些小问题， 遇到问题分析问题解决问题～

1.Actions 始终显示

Waiting for a runner to pick up this job...

解决办法： 仓库 settings - actions - Workflow permissions 选择第一项：Read and write permissions

2.首页资源访问异常

解决办法： 设置 vite.config.js base 配置项目, 参考Vite文档

export default defineConfig({
  base: '/winsax/', // 设置 base https://cn.vitejs.dev/guide/static-deploy#github-pages
  plugins: [react()],
})

github 不稳定

出现 github 服务器无响应一半是访问速度慢或者不稳定造成～ 等恢复或者 [ 🚀 ...]

本文完