【保姆级教程】手把手教你如何快速在Github部署自己的静态网页

原创于 2026-05-17 21:04:54 发布 · 520 阅读

5 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#github #部署 #0成本网页 #网页托管 #项目

Github 专栏收录该内容

1 篇文章

订阅专栏

在日常开发中，我们经常需要部署一些简单的静态页面来展示项目或分享文件。GitHub Pages 作为一款免费、稳定且与 Git 深度集成的静态网站托管服务，是个人博客、项目文档和作品展示的理想选择。本教程将手把手带你完成从部署静态页面到实现文件下载的全过程。

一、将静态 HTML 网页部署到 GitHub Pages

1.1 创建 GitHub 仓库

首先，登录你的 GitHub 账号，点击右上角的「+」→「New repository」创建一个新仓库。仓库命名有两种方式：

方式一：用户/组织站点（推荐新手使用）

仓库名必须命名为 你的用户名.github.io，例如 zhangsan.github.io。这是个人主页的唯一命名规则。部署完成后，直接访问 https://你的用户名.github.io 即可。

方式二：项目站点

仓库名可以随意命名，例如 my-project。部署完成后访问 https://你的用户名.github.io/my-project。

注意：如果要使用 GitHub Pages 的免费服务，仓库必须设为 Public（公开），Private 仓库需要付费计划才能使用 Pages 功能。

1.2 准备你的网页文件

在本地创建一个文件夹，放入你的网页文件。最简单的结构如下：

my-site/
├── index.html      # 首页（必须存在）
├── css/
│   └── style.css   # 样式文件
├── js/
│   └── main.js     # 脚本文件
└── files/          # 存放可供下载的文件
    └── example.pdf

index.html 是 GitHub Pages 默认寻找的入口文件，必须放在仓库根目录或 /docs 目录下。一个最简单的 index.html 示例如下：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>我的 GitHub Pages</title>
    <link rel="stylesheet" href="css/style.css">
</head>
<body>
    <h1>欢迎来到我的网站！</h1>
    <p>这是一个部署在 GitHub Pages 上的静态网页。</p>
</body>
</html>

1.3 将代码推送到 GitHub

在本地项目文件夹中打开终端，依次执行以下命令：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>我的 GitHub Pages</title>
    <link rel="stylesheet" href="css/style.css">
</head>
<body>
    <h1>欢迎来到我的网站！</h1>
    <p>这是一个部署在 GitHub Pages 上的静态网页。</p>
</body>
</html>

1.4 启用 GitHub Pages

推送成功后，进入你的 GitHub 仓库页面，按以下步骤操作：

点击仓库顶部的 Settings 标签页
在左侧菜单中找到并点击 Pages
在「Build and deployment」的 Source 下拉框中，选择 Github Actions
点击Static Html 下方按钮直接commit
点击 commit change

保存后，GitHub 会自动开始部署，通常 1-2 分钟后就能访问了。在上方 Actions 页面上会显示你的任务进度，点击即可预览。

1.5 常见问题排查

如果在部署过程中遇到问题，可以从以下几个方面检查：

网站不显示或显示 404？

首先确认 index.html 是否在仓库的根目录下（或你设置的发布目录下），文件名是否拼写正确。

加了 .nojekyll 文件（若没有选择第一个jekyll可直接跳过）

GitHub Pages 默认会使用 Jekyll 处理你的网页文件。如果你的页面在本地正常显示，部署后却样式错乱或部分内容不显示，很可能就是这个原因。解决方法很简单：在项目根目录创建一个名为 .nojekyll 的空文件，告诉 GitHub Pages 跳过 Jekyll 处理，直接按纯静态文件对待。

路径问题

GitHub Pages 对文件名大小写敏感，请确保 HTML 中引用的资源路径与实际文件名大小写完全一致。另外，如果使用的是项目站点（非 username.github.io 仓库），网页中引用资源的路径可能需要加上项目名前缀，例如 /my-project/css/style.css。

缓存问题

部署更新后，浏览器可能加载的是旧版本。可以尝试按 Ctrl + F5（Windows）或 Cmd + Shift + R（Mac）强制刷新。

二、在网页中实现文件下载功能

网页部署好了，接下来我们看看如何让访问者下载文件。这里有三种常见方式，从简单到灵活，适合不同场景。

方式一：使用 `<a>` 标签的 `download` 属性（最简单）

HTML5 为 <a> 标签引入了 download 属性，点击链接时浏览器会直接下载文件，而不是尝试打开它。这是最直接、最简单的方法。

基本用法：

html

<!-- 直接下载，保留原文件名 -->
<a href="files/example.pdf" download>下载 PDF 文件</a>

<!-- 指定下载后的文件名 -->
<a href="files/report.pdf" download="年度报告.pdf">下载年度报告</a>

操作步骤：

将需要下载的文件（如 PDF、Word、压缩包等）放入仓库目录中，例如放在 files/ 文件夹下
在 index.html 中添加上述 <a> 标签
href 使用相对于网站根目录的路径即可
提交并推送代码，等待部署完成

支持的常见文件类型： PDF、Word 文档、Excel 表格、图片（jpg/png/gif）、压缩包（zip/rar）、音频/视频文件等。

注意事项：

download 属性仅对同源 URL 有效——即文件必须放在你自己的 GitHub Pages 网站上。如果链接指向其他网站的资源，浏览器出于安全考虑会忽略 download 属性。
建议将文件放在网站同一域名下，使用相对路径最为稳妥。
部分旧版浏览器（如 IE）不支持该属性。

方式二：用 JavaScript 动态触发下载

上面的方法适合下载已经存在于仓库中的静态文件。但如果文件 URL 是动态生成的，或者需要在下载前做一些判断和处理，用 JavaScript 会更灵活。

核心思路是：用 JavaScript 动态创建 <a> 标签，设置好 href 和 download 属性，然后模拟点击触发下载。

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>文件下载示例</title>
</head>
<body>
    <h2>请选择你要下载的文件：</h2>

    <button οnclick="downloadFile('files/guide.pdf', '使用指南.pdf')">
        下载使用指南
    </button>

    <button οnclick="downloadFile('files/template.zip', '模板文件.zip')">
        下载模板文件
    </button>

    <script>
        function downloadFile(filePath, fileName) {
            // 动态创建 <a> 标签
            const link = document.createElement('a');
            link.href = filePath;        // 文件路径
            link.download = fileName;    // 下载后的文件名
            document.body.appendChild(link);
            link.click();                // 模拟点击触发下载
            document.body.removeChild(link); // 下载完成后移除元素
        }
    </script>
</body>
</html>

这种方式的好处是可以在 downloadFile 函数中加入任何你需要的逻辑，比如根据用户选择动态拼接文件路径、做权限校验、记录下载次数等。

方式三：用 JavaScript 动态生成文件并下载

更高级的场景是：文件并非事先存在，而是需要在用户点击时动态生成——比如导出用户填写的内容、生成配置文件、导出表格数据等。这时可以借助 JavaScript 的 Blob 对象来实现。

原理简述： 将文本或数据封装成 Blob 对象 → 用 URL.createObjectURL() 生成临时 URL → 通过动态 <a> 标签触发下载 → 下载完成后释放内存。

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>动态生成文件并下载</title>
</head>
<body>
    <h2>动态生成文件下载</h2>

    <textarea id="content" rows="6" cols="40" placeholder="在这里输入内容...">
这是示例内容。
你可以修改这些文字，然后下载为文本文件。
    </textarea>
    <br><br>

    <button οnclick="downloadGeneratedFile()">
        下载为文本文件
    </button>

    <script>
        function downloadGeneratedFile() {
            // 获取用户输入的内容
            const text = document.getElementById('content').value;

            // 创建 Blob 对象
            const blob = new Blob([text], { type: 'text/plain;charset=utf-8' });

            // 生成临时 URL
            const url = URL.createObjectURL(blob);

            // 动态创建 <a> 标签并触发下载
            const link = document.createElement('a');
            link.href = url;
            link.download = '我的文件.txt';
            document.body.appendChild(link);
            link.click();

            // 清理：移除元素并释放内存
            document.body.removeChild(link);
            URL.revokeObjectURL(url);
        }
    </script>
</body>
</html>

这里的关键点：

new Blob([text], { type: '...' })：将文本数据转换成 Blob 文件对象，type 指定 MIME 类型
URL.createObjectURL(blob)：为 Blob 创建一个临时的浏览器内存 URL
URL.revokeObjectURL(url)：下载完成后释放内存，避免内存泄漏

这个方法可以扩展为导出 CSV 表格、生成 JSON 配置文件、甚至是前端截图后导出图片等多种场景。

三、完整项目示例

下面是一个整合了上述三种下载方式的完整网页示例，你可以直接拿去使用：

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>GitHub Pages 文件下载演示</title>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
            max-width: 700px;
            margin: 40px auto;
            padding: 0 20px;
            line-height: 1.8;
            color: #333;
        }
        h2 { border-bottom: 2px solid #eee; padding-bottom: 8px; margin-top: 30px; }
        a, button { margin: 5px 10px 5px 0; }
        button {
            padding: 8px 16px;
            background: #0366d6;
            color: #fff;
            border: none;
            border-radius: 5px;
            cursor: pointer;
        }
        button:hover { background: #0256b9; }
        textarea { width: 100%; padding: 10px; border: 1px solid #ccc; border-radius: 5px; }
    </style>
</head>
<body>

    <h1>📦 文件下载功能演示</h1>

    <!-- 方式一：静态文件下载（记得把文件放到 files/ 目录下） -->
    <h2>1. 静态文件下载（a标签 + download属性）</h2>
    <a href="files/sample.pdf" download>📄 下载 PDF 示例</a>
    <a href="files/sample.zip" download>📦 下载压缩包示例</a>

    <!-- 方式二：JavaScript 动态触发 -->
    <h2>2. JavaScript 动态触发下载</h2>
    <button οnclick="downloadFile('files/sample.pdf', '使用手册.pdf')">
        📥 下载 PDF（指定文件名）
    </button>

    <!-- 方式三：动态生成文件 -->
    <h2>3. 动态生成文件并下载</h2>
    <textarea id="content" rows="5">在这里写点内容，然后点击下载按钮保存为文本文件。</textarea>
    <br>
    <button οnclick="downloadGeneratedFile()">💾 下载为文本文件</button>

    <script>
        // 方式二：动态触发下载已有文件
        function downloadFile(filePath, fileName) {
            const link = document.createElement('a');
            link.href = filePath;
            link.download = fileName;
            document.body.appendChild(link);
            link.click();
            document.body.removeChild(link);
        }

        // 方式三：动态生成文件内容并下载
        function downloadGeneratedFile() {
            const text = document.getElementById('content').value;
            const blob = new Blob([text], { type: 'text/plain;charset=utf-8' });
            const url = URL.createObjectURL(blob);
            const link = document.createElement('a');
            link.href = url;
            link.download = '我的笔记.txt';
            document.body.appendChild(link);
            link.click();
            document.body.removeChild(link);
            URL.revokeObjectURL(url);
        }
    </script>

</body>
</html>

github的Release里的包下载地址（永久）

https://www.github.com/用户名/仓库名/Release/加上那个里面的包名（记得后缀，其实就是那个文件名）

四、总结

本文介绍了三大块内容：

部署静态网页到 GitHub Pages：创建仓库 → 推送代码 → 在 Settings 中启用 Pages → 完成。核心要点是确保 index.html 存在、必要时添加 .nojekyll 文件，以及注意路径的大小写敏感性。
实现文件下载的三种方式：
- 方式一（最简单） ：用 <a> 标签的 download 属性，适合下载仓库中的静态文件。
- 方式二（较灵活） ：用 JavaScript 动态创建 <a> 标签触发下载，适合需要动态拼接 URL 的场景。
- 方式三（最强大） ：用 JavaScript + Blob 动态生成文件内容并下载，适合导出数据、生成配置文件等场景。
一个可直接使用的完整示例，整合了以上三种方式，开箱即用。