你有没有过这种经历本地把网页做得漂漂亮亮想发给朋友看看效果结果又是压缩包又是网盘链接对方下载完还得解压双击 index.html样式还经常跑掉。把本地网页放到 GitHub 上用 GitHub Pages 生成一个在线网址是解决这个问题的标准做法也是前端开发者必备的基础技能。这篇文章我打算从一个完全新手也能跟上的角度把“上传本地网页到 GitHub 并生成网址”的完整过程拆开揉碎讲一遍。整个过程不需要你懂复杂的命令行原理也不需要花钱买服务器只要你照着步骤往下走大概十几分钟就能拿到一个属于自己的线上链接。无论你是在校学生交作业还是想给项目做个展示页又或者单纯想把简历里加上一个在线作品集这篇文章都适合你。1. 先搞清楚整套流程的核心逻辑1.1 GitHub Pages 到底是什么很多人第一次听说 GitHub Pages 会误以为它是个什么高深的东西其实它的本质就是一个静态网页托管服务。所谓“静态网页”简单理解就是不需要后台服务器动态计算、由 HTML、CSS、JavaScript 直接构成的网页。你的浏览器打开这类网页时不需要向服务器发请求去“生成”内容直接把文件下载下来解释渲染就行。GitHub Pages 的运作方式特别直白你创建一个仓库把网页文件传上去然后在仓库设置里开启 Pages 功能GitHub 就会自动为这个仓库生成一个形如用户名.github.io/仓库名的访问地址。以后你每次往仓库里推新代码线上网址会自动同步更新省去了手动上传到服务器、手动部署的繁琐过程。1.2 为什么选择 GitHub 而不是其他方式关于部署静态网页市面上确实有不少选择比如 Gitee Pages、Netlify、Vercel、Cloudflare Pages 等。但我个人建议新手第一站选 GitHub理由有几点。第一GitHub 是全球最大的代码托管平台你的账号往后不只是用来放这一个网页还能用来参与开源项目、保存自己各种代码片段一份投入长期复用。第二GitHub Pages 免费而且不限制流量合理使用范围内对一个个人作品展示页来说完全够用。第三GitHub Pages 支持绑定自定义域名以后你如果想给网页换个更专业的网址不用迁移平台。第四网上关于 GitHub 的中文教程数量庞大遇到问题搜起来方便。当然GitHub 服务器部署在海外国内访问偶尔会有连接不稳定的情况。如果你发现自己访问 GitHub 官网特别慢可以先检查本地网络环境也可以尝试国内网络正常时段的访问情况。需要注意市面上那些所谓“加速器”“镜像站”存在账号安全和代码泄露风险我不推荐也不建议使用正常网络环境下操作流程完全能走通。1.3 整条链路的三个环节为了让你对后面的大段操作心里有数我把整条链路概括为三个阶段。第一阶段是准备期注册 GitHub 账号、本地安装 Git、检查电脑环境。第二阶段是推送期在本地把网页文件夹变成 Git 仓库提交代码推送到 GitHub 远程仓库。第三阶段是发布期在 GitHub 仓库设置里开启 Pages拿到网址访问验证。这三个阶段里第二阶段对新手来说是最容易卡住的地方因为涉及到 Git 命令行操作。不过别紧张你需要用到的 Git 命令翻来覆去就那么几个我会逐个解释它们的作用你不需要死记硬背理解逻辑之后自然就记住了。2. 实操前的准备工作与环境搭建2.1 注册 GitHub 账号并完善资料如果你还没有 GitHub 账号先去官网github.com点击右上角的 Sign up 注册。注册过程需要填写邮箱、设置密码、验证账号没什么特别的门槛。这里我多说一句用户名一定要认真想因为你的 Pages 网址里会带上用户名比如我注册时用的用户名是demo123那我的 Pages 主站地址就是demo123.github.io。这个用户名注册之后虽然可以改但改起来牵扯到仓库地址变更很麻烦不如一开始就选好。注册完成之后建议顺手把头像和个人简介填一下。你可能觉得这一步无所谓但实际上后期如果你把这个链接发给面试官或者客户对方大概率会点进你的主页看一眼。一个完整的个人主页显得你做事认真。2.2 本地安装 Git 并验证是否成功Git 是一个版本控制工具你可以把它理解成一个“时光机记录员”专门帮你记录文件夹里每个文件的每一次变化。推送代码到 GitHub 这件事底层就是靠 Git 来完成的。Windows 用户直接去 Git 官网下载安装包一路默认选项点下一步即可。macOS 用户如果装了 Homebrew可以执行brew install git没装的话去官网下载 macOS 版安装包也一样。Linux 用户用系统自带的包管理器装比如 Ubuntu 执行sudo apt install git。安装完成之后打开终端Windows 上打开 PowerShell 或 CMDmacOS 打开终端输入git --version如果看到类似git version 2.39.2的输出说明安装成功。这一步卡住的人很少如果提示找不到命令大概率是安装路径没加入环境变量重新安装时勾选“Add to PATH”选项即可。2.3 配置 Git 的用户名和邮箱Git 安装好之后需要告诉它“你是谁”这样每次提交代码时Git 会在记录里留下你的名字和邮箱。打开终端执行下面的命令替换成你自己的信息git config --global user.name 你的GitHub用户名 git config --global user.email 你注册GitHub用的邮箱--global参数表示全局生效你这台电脑上所有 Git 仓库都会默认使用这个身份信息。这一步虽然不配置也能往下走但后期查看提交历史时会显示一堆 “unknown” 或乱码很影响观感建议提前做好。3. 准备一个适合发布的本地网页项目3.1 本地网页文件夹的标准结构在开始推送之前先检查一下你的本地网页文件夹。我见过很多新手把自己整个开发目录、node_modules 文件夹、各种 psd 源文件一股脑推送到仓库里结果仓库体积巨大网页加载还慢。一个标准的静态网页项目最精简的结构是my-page/ ├── index.html ├── css/ │ └── style.css ├── js/ │ └── main.js └── images/ └── logo.pngindex.html是入口文件GitHub Pages 在生成网址时会自动寻找仓库根目录下这个文件。如果你的网页不是以index.html命名比如叫home.html访问网址时就需要手动在链接末尾加上home.html否则会显示 404。所以你在发布前最好把主页文件名统一改成index.html。3.2 资源引用路径的一个关键坑这一点非常关键我单独拎出来说。你在本地写网页时如果引用了外部文件比如 CSS、图片或 JS路径分两种绝对路径和相对路径。绝对路径的问题在于它可能写的是本地电脑上的完整路径比如link relstylesheet hrefC:/Users/你的用户名/Desktop/my-page/css/style.css这种路径换一台电脑就无法识别发布到 GitHub Pages 之后也一定会失效。正确的做法是使用相对路径也就是相对于当前 HTML 文件所在位置的路径link relstylesheet hrefcss/style.css意思是“和 index.html 同目录下的 css 文件夹里的 style.css”。同理图片引用写成images/logo.pngJS 引用写成js/main.js。只要你保证本地网页双击打开时样式、图片都正常推送到 GitHub Pages 之后大概率也会正常。如果你是 Vue、React 这类工程化项目构建产物是 dist 目录情况稍微复杂一点因为打包时资源的 base 路径可能需要调整。不过这篇文章主要面向静态网页场景工程化项目的内容以后单独再写。3.3 建议添加一个 README 文件README 文件是仓库的“说明书”GitHub 会自动把它渲染在仓库首页。虽然不是部署必需的但我建议你写上因为它对别人了解你的项目很有帮助。README.md 使用 Markdown 格式编写最简单的写法是# 我的个人主页 这是一个展示个人作品的静态网页基于 HTML/CSS 构建。 ## 访问地址 https://你的用户名.github.io/你的仓库名/你甚至可以先用三行字把它写出来后期项目复杂了再逐步补充。别小看这个文件面试官或者访客点进仓库时第一眼看到的就是它。4. 在 GitHub 上创建远程仓库4.1 新建仓库时的关键选项登录 GitHub 之后点击页面右上角的加号图标选择 New repository进入创建页面。这里有几个选项需要说明一下。Repository name仓库名是必填项它同时会出现在你的访问网址里。建议用小写字母、数字和短横线组合不要用中文和空格比如my-portfolio、web-demo、responsive-page。另外仓库名不要和用户名重名因为用户名.github.io这个名称有特殊含义它代表的是个人主站仓库和咱们这次要创建的普通仓库用途不太一样。Description描述是选填项可以简单写一句“我的个人网页项目”之类的话方便自己和别人识别。Visibility可见性这里要特别注意新手容易选错。Public公开表示任何人都能看见你的代码Private私有表示只有你自己能看到。因为咱们要用 GitHub Pages 生成公开网页仓库必须设置为 Public。你可能会担心代码公开泄露隐私其实静态网页项目的源码通常不含敏感信息只要你没在代码里写密码、密钥之类的东西公开完全没问题。最后还有一项 “Add a README file” 以及 .gitignore、license 的选择。对于这次的场景我建议 README 先不勾选因为你本地已经有网页文件了等推送到远程仓库之后在 GitHub 网页上直接编辑 README 会更顺手。.gitignore 如果不太了解先不用勾选后面推送时把无关文件手动控制好就行。点击 Create repository 之后GitHub 会跳转到一个新页面上面展示了几种推送代码的方式。这个页面先别关等会儿要用到上面的仓库地址。4.2 理解远程仓库地址的两种格式GitHub 推送代码时需要告诉 Git 远程仓库的地址。这个地址有两种形式HTTPS 格式和 SSH 格式。HTTPS 格式长这样https://github.com/你的用户名/仓库名.gitSSH 格式长这样gitgithub.com:你的用户名/仓库名.git新手第一次操作我建议先用 HTTPS 格式因为它的配置环节最少只要在推送时输入 GitHub 的用户名和密码密码在 2021 年之后变成了 Personal Access Token就能完成。SSH 格式需要你先在本机生成密钥对再把公钥配置到 GitHub 账号里加密性更强往后推送时不用重复输账号密码但对新手来说建立心智负担。4.3 关于个人访问令牌Personal Access Token的说明如果你使用 HTTPS 方式推送代码在 2021 年 8 月之后GitHub 不再支持直接用账号密码作为认证凭据而是要求使用 Personal Access Token简称 PAT。简单理解PAT 就是一个由你自己生成的、带有特定权限的“专用密码”。在 GitHub 网页右上角头像那里依次点击 Settings - Developer settings - Personal access tokens - Tokens (classic) - Generate new token (classic)。生成时你可以给它起个名字比如local-git-push然后勾选repo权限范围有效期建议选择 90 天或者更短到期后需要重新生成。生成的 Token 只显示一次一定要先复制保存好否则页面刷新之后就看不到了。第一次用 HTTPS 推送时命令行会提示输入用户名和密码用户名填你的 GitHub 用户名密码那一栏粘贴刚才复制的 Token 即可。注意终端输入密码时不会显示任何字符不是卡住了直接粘贴回车就行。5. 本地网页推送到 GitHub 的完整实操5.1 初始化本地 Git 仓库假设你现在已经打开终端并且用cd命令进入了你的网页根目录。比如你的网页文件夹在桌面上的my-page文件夹里那就执行cd Desktop/my-page在 Windows 上如果路径有空格记得用引号包起来比如cd Desktop/我的页面文件夹。确保当前目录里能看到你的index.html文件然后执行git init这个命令的作用是在当前文件夹里创建一个隐藏的.git目录这个目录就是 Git 的“档案库”你后面所有的版本记录都存在这里面。执行成功后终端会提示Initialized empty Git repository之类的字样。5.2 把文件加入暂存区接下来执行git add .注意这个点号它表示“把当前目录下所有文件都加入暂存区”。所谓暂存区你可以把它理解成一个“待提交清单”你想让 Git 记录哪些文件就先把它放进这个清单里。如果你只想添加某个特定文件可以写成git add index.html但通常一个网页项目直接全部添加就行。执行完之后可以用git status查看当前状态会看到类似这样的一段输出Changes to be committed: (use git rm --cached file... to unstage) new file: index.html new file: css/style.css new file: js/main.js5.3 提交代码生成第一个版本记录暂存区准备好了之后执行git commit -m 首次提交网页项目-m参数后面跟的是本次提交的说明文字。新手容易忽略这个步骤或者不写说明直接回车结果 Git 会跳到一个 Vim 编辑器界面新手在里面不知道如何退出很容易卡住。如果你不小心进去了按一下键盘左上角的Esc键然后输入:wq再按回车就能退出并完成提交。提交成功后会显示类似1 file changed, 10 insertions()的信息意思是这次提交改了哪些文件、加了多少行代码。5.4 关联远程仓库并推送现在到了最关键的一步。回到 GitHub 创建仓库后跳转的那个页面复制 HTTPS 地址然后执行git remote add origin https://github.com/你的用户名/仓库名.git这条命令的意思是给本地仓库绑定一个名为origin的远程地址引用。所谓 origin 只是约定俗成的名字不是硬性规定你可以把它理解成一个“快捷方式名”以后推送时不需要每次输入完整的远程地址。绑定完成之后执行推送命令git push -u origin main这里的main是本地仓库默认分支的名称。前几年 GitHub 新建仓库的默认分支叫master后来统一改成了main。如果推送时提示分支名不匹配很可能是你本地分支叫master而远程叫main可以先执行git branch -M main把本地分支重命名再重新推送。-u参数全称是--set-upstream作用是把本地分支和远程分支关联起来以后再执行git push时就可以不加参数了。第一次推送时命令行可能会弹出一个窗口让你登录 GitHub按照网页提示完成授权即可。如果提示输入密码记住要粘贴的是刚才生成的 Token不是你的登录密码。推送成功的标志是出现类似Branch main set up to track remote branch main from origin.的提示。到此为止你的代码已经躺在了 GitHub 的远程仓库里。6. 开启 GitHub Pages 并生成访问网址6.1 找到 Pages 设置页面打开你的 GitHub 仓库页面点击顶部导航栏的 Settings然后在左侧边栏找到 Pages 选项。这一步很多新手会找半天因为 Settings 里选项非常多记得用浏览器自带的查找功能CtrlF 或 CommandF搜一下 Pages 就能快速定位。6.2 构建部署配置进入 Pages 设置页面后在 Build and deployment 区域你会看到 Source 下拉菜单。默认情况下可能需要选择分支部署点击下拉菜单把它改成Deploy from a branch然后选择分支为main目录为/ (root)最后点击 Save 按钮。注意如果这里没有自动出现分支选择说明你的仓库里还没有任何提交记录回到本地终端执行一次git push确认代码已经推上去。另外如果仓库里存在gh-pages分支那是 GitHub Actions 之类的工作流自动生成的这次不需要理会。保存之后页面会显示一个网址形式是https://你的用户名.github.io/你的仓库名/但这个网址不会立刻生效因为 GitHub 需要在后台构建和部署你的网页。通常会有一个“黄灯”状态表示正在发布中等一两分钟后刷新页面地址旁边出现绿色勾号就表示部署成功了。6.3 通过 Actions 面板观察部署状态如果你部署过程中一直打不开网址可以点击仓库顶部的 Actions 选项卡你会看到一条以pages build and deployment命名的工作流记录。点进去可以看到部署日志如果有报错也会显示在日志里。这里顺带说明一下GitHub Pages 的部署机制现在有两种方式一种是刚才说的从分支直接部署另一种是使用 GitHub Actions 配置文件.github/workflows/目录下的 yml 文件来实现自动化部署。对于静态网页来说分支部署方式最简单够用不建议为了炫技刻意上 Actions除非你用的是 Hugo、Jekyll 这类静态站点生成器又有额外的构建步骤。6.4 访问网址并验证部署结果在浏览器地址栏输入刚才那个网址如果一切正常你应该能看到和本地完全一致的页面。这里我列几个部署成功后的快速检查项。第一检查标题和内容是否正确显示。第二按 F12 打开开发者工具切到 Network 标签页刷新页面看看有没有红色的请求记录。如果有红色记录点进去看是哪个文件加载失败大概率是你之前提到的路径引用问题。第三用手机访问同一个网址看看布局是否正常。如果网址打不开出现 404 页面显示404 There isnt a GitHub Pages site here.一般有三种原因仓库里没有index.html、部署还没有完成、或者网址拼写错误。逐一排查即可。7. 日常更新与项目维护技巧7.1 本地修改后如何更新到线上你第一次发布成功之后接下里的场景就是不断修改网页然后让线上的版本同步更新。更新流程比首次推送简单得多总共三条命令git add . git commit -m 修改了首页样式 git push第一次推送时你已经加了-u参数所以后面第 3 条命令直接git push就行了。Git 会自动把本地的 main 分支推送到关联的远程分支。推送成功后GitHub Pages 会重新构建部署等一两分钟线上网页就是最新效果了。这里我需要提醒你一个习惯问题不要偷懒只执行git push而不写提交信息。如果你改了代码却不 commit 直接 pushGit 会提示nothing to commit, working tree clean也就是说它根本没有检测到任何变化。版本控制的意义在于每一次提交都对应一个明确的修改描述将来回溯问题时才能知道哪次修改引入了问题。7.2 如何删除仓库里的多余文件如果你第一次推送时不小心把一些无关文件推上去了比如node_modules文件夹或者本地备份文件清理方式如下。首先在本地把那些文件删掉确认没问题之后依次执行git rm -r --cached 文件名或文件夹名 git commit -m 删除不需要的文件 git push分批把不需要的文件从 Git 的跟踪记录里移除最后推送到远程。注意加--cached参数的意思是仅仅从 Git 记录中移除不会删除你本地磁盘上的文件。如果误操作了用git checkout -- 文件名可以撤销恢复。不过我更建议你从一开始就养成习惯在项目根目录创建.gitignore文件把不需要纳入版本管理的文件或目录写进去比如node_modules/ .DS_Store *.log这样执行git add .时Git 会自动跳过这些文件和目录从源头上防止垃圾文件进仓库。7.3 给项目加自定义域名进阶如果你自己有一个域名想要把它绑定到 GitHub Pages 上操作也不复杂。你需要在仓库 Settings 的 Pages 页面里找到 Custom domain 一栏填上你的域名比如www.example.com然后按照提示在你的域名服务商那里添加一条 CNAME 记录指向你的用户名.github.io再回到 GitHub 页面点击 Save。GitHub 会根据提示自动为你的域名申请 HTTPS 证书。这一步的安排是先去域名服务商后台把 DNS 解析配上等生效后再回来填 GitHub 这边的设置。最好先在账号根目录下的用户名.github.io仓库中配置否则会出现域名解析跳转异常的情况。如果你只是想快速体验上线效果自定义域名完全不急后面有需要再说。8. 常见问题与排查技巧实录8.1 首次 push 时提示 Permission denied这是一个非常高频的报错。如果你是 Windows 用户命令行里通常会出现Permission denied (publickey)之类的提示而这个提示多半发生在你选择了 SSH 方式但还没有配置 SSH 公钥的时候。解决思路分两步。第一步检查你当前用的远程地址是不是 SSH 格式执行git remote -v如果是gitgithub.com:...开头而你还没配置 SSH key建议直接换回 HTTPS 格式git remote set-url origin https://github.com/你的用户名/仓库名.git第二步如果你确实想用 SSH 方式那就需要生成密钥ssh-keygen -t ed25519 -C 你的邮箱一路回车之后执行cat ~/.ssh/id_ed25519.pub复制输出内容然后到 GitHub 的 Settings - SSH and GPG keys - New SSH key 粘贴保存。之后再测试连接ssh -T gitgithub.com显示成功即可。8.2 push 时提示 Repository not found出现这个提示通常不是你的代码有问题而是仓库地址填错了。我碰到过好几次是新手复制地址时多复制了一个空格或者仓库名和用户名写反了。检查方式执行git remote -v看看当前绑定的地址再和 GitHub 仓库页面的地址对照一下。如果确实发现地址不对执行git remote set-url origin https://正确的地址.git重新绑定一遍就行。另外还有一种情况你本地仓库还没关联远程地址直接执行git push时 Git 不知道推到哪里去也会报类似的错。这时候重新执行一次git remote add origin 地址就行。8.3 网页上线了但样式错乱打开线上链接文字有但图片裂了、CSS 完全没生效这是典型的路由路径问题。排查思路很直接打开浏览器开发者工具切到 Console 和 Network 标签页看有没有 404 的请求你就能看到浏览器到底在哪个路径下找资源。比如页面报错说找不到/css/style.css而你本地明明有这个文件大概率是因为代码里用了绝对路径比如/css/style.css以斜杠开头在本地时它被解析成file:///C:/css/style.css这种本地绝对路径发布到线上后则被解析成了https://你的用户名.github.io/css/style.css。这显然不对因为没有这个目录。解决方式就是把绝对路径改成相对路径去掉开头的斜杠改成css/style.css就行。另一种情况是你的仓库名里有大写字母导致页面按仓库名生成的子路径出现了大小写不匹配的问题。GitHub 仓库名不区分大小写但网址访问时区分所以建议仓库名全部用大写URL 里的大小写与仓库名的实际大小写保持一致。更稳妥的做法是仓库名从头到尾全用小写字母。8.4 网址能打开但是 404 页面这种情况一般出现在仓库根目录下没有index.html或者index.html命名大小写有误。GitHub Pages 默认只认小写开头的index.html如果你的文件叫Index.html或INDEX.html都可能识别不到。另外如果你第一次部署的是个空仓库或者只有 README 文件后面的提交还没推上来那网址也会显示 404。这种情况下回到本地终端确认一下git push是否成功然后在 GitHub 仓库页面看文件名是否和本地一致。8.5 国内网络访问 GitHub Pages 缓慢或不稳定这个问题确实存在。因为 GitHub 的服务器部署在海外国内用户在访问时可能会遇到加载慢、卡顿甚至打不开的情况。面对这个问题我能给你的最实际建议就是在常规网络状态下多刷新几次或者换一个时间段再试。如果你有比较着急的演示需求也可以考虑把网页同步部署到国内能正常访问的平台然后把 GitHub Pages 作为代码展示窗口。这里必须提醒一句网上流传的各种“GitHub 加速工具”或者来路不明的“镜像站”不仅存在账号被盗的风险而且可能篡改你的代码内容千万不要用更不要往里面填个人信息和 Token。8.6 如何备份和回退到旧版本有一次我维护一个网页项目时不小心把 CSS 改乱了页面变得没法看。当时最想做的事就是把线上版本退回到几天前的正常状态。Git 在这方面完美胜任。先查看提交历史git log --oneline你会看到类似这样几行输出a1b2c3d (HEAD - main) 修改了首页样式 e4f5g6h 添加了项目展示区 x7y8z9w 首次提交网页项目每一行代表一次提交前面的字符串是提交的哈希值。如果你想退回到e4f5g6h这个版本执行git reset --hard e4f5g6h这条命令会把本地代码完全恢复到那个版本的状态然后再执行git push --force强制推送覆盖远程。需要特别注意的是--hard参数非常危险它会丢弃当前所有未提交的改动执行前一定三思。更安全的做法是先用git stash把当前改动暂时保存起来或者开一个分支进行回退操作确认没问题之后再合并。新手使用这个命令之前最好把当前文件另存一份备份。9. 自动化部署的进阶扩展思路9.1 借助 GitHub Actions 实现推送自动构建前面我提到线上的网页会在你每次推送后自动更新这个机制是 GitHub Pages 内置的。但是如果你用的是 Hugo、Hexo 这类静态站点生成器构建过程不是单纯把仓库里的文件原样提供服务而需要在服务器上执行一段构建命令生成最终的 HTML 文件之后才能上线。GitHub Actions 解决的就是这个问题。你可以在仓库里创建一个.github/workflows/deploy.yml文件定义一套工作流当代码推送到 main 分支时自动在 GitHub 的虚拟机上安装依赖、执行构建命令、把构建产物发布到 Pages 上。不过这属于进阶玩法。如果你是纯手写的 HTML/CSS/JS没有构建这步没必要上 Actions因为分支直接部署的方式已经把你需要的自动化全都做好了。9.2 上传整个文件夹而不是单个文件有些人习惯在 GitHub 网页端直接拖拽上传文件但这种方式有个限制一次只能上传一定数量的文件而且不支持上传空文件夹。如果你项目里有大量图片和 CSS 文件网页端上传会非常痛苦。正确的做法还是用本地 Git 推送一次性把所有文件和文件夹结构原封不动地推上去。Git 对文件夹的支持是原生的空文件夹除外——Git 本身不记录空文件夹如果你的项目中必须有空的目录结构可以在里面放一个.gitkeep文件占位。9.3 多项目共用一个域名你的 GitHub 账号下面可以创建无数个仓库每个仓库都能开启 Pages对应各自的网址。也就是说你的作品展示页、实验小工具、个人简历网站都可以分门别类地放在不同的仓库里互不干扰。这里有一个常用套路创建一个用户名.github.io仓库作为个人主站其他项目仓库作为子项目。开启 Pages 后项目仓库的访问地址是用户名.github.io/仓库名主站地址则是用户名.github.io。你可以在主站首页放上所有子项目的导航链接形成一个作品集合页。10. 我踩过的坑和给你的最后建议10.1 我经历过的一次“翻车”经历有一次我给一个客户做产品展示页本地预览一切正常兴冲冲推送到 GitHub 开启 Pages结果客户发来消息说网址打不开。我打开一看页面显示 404。我排查了很久最后发现原因是仓库名里包含大写字母而我访问网址时全写了小写。GitHub 仓库默认不区分大小写但 Pages 生成的网址对大小写敏感。那次之后我新建仓库一律只用小写字母和短横线彻底杜绝这类问题。还有一个高频翻车点是第一次推送时没有先创建远程仓库直接在本地执行git push -u origin main系统提示remote origin not found。这就像寄快递还没填写收件人地址一样快递员没办法收件。所以创建远程仓库、绑定 origin、推送这三步的顺序不能乱。10.2 给新手的操作清单最后整理一份完整的操作顺序清单你只需要按顺序逐项完成即可注册 GitHub 账号已注册的跳过。本地安装 Git 并验证版本号。配置 Git 用户名和邮箱。检查本地网页根目录下是否有index.html文件并将 CSS/JS/图片路径改为相对路径。在 GitHub 网页端创建新仓库Public仓库名使用小写字母和短横线。在本地网页根目录打开终端执行git init。执行git add .把文件加入暂存区。执行git commit -m 首次提交生成提交记录。执行git remote add origin 你的仓库地址绑定远程仓库。执行git branch -M main确保分支名是 main。执行git push -u origin main推送代码。在 GitHub 仓库 Settings - Pages 里选择 main 分支并保存。等待 1-2 分钟访问用户名.github.io/仓库名验证效果。这套流程第一次走完可能有点手忙脚乱但只要你完整走通一次后面再上传新的网页项目整个流程不会超过三分钟。10.3 从“上传网页”到“管理项目”的进阶路径当你把第一个网页成功上线意味着你已经掌握了 Git 的最核心工作流程初始化仓库、提交代码、关联远程、推送更新。这套流程不只是用来传网页它也是日后参与开源项目、写个人博客、甚至团队协作开发的基础。接下来我建议你可以尝试做的扩展方向包括把个人简历做成一个静态网页并部署上线把网址写进简历里。学习使用 GitHub Issues 和 Projects 来记录自己项目的待办事项和开发计划。尝试给别人的开源项目提一个 Issue 或者提交一个 Pull Request体验开源协作的完整链路。学一点 Markdown 语法把 README 写得漂漂亮亮让别人一眼看懂你的项目是做什么的。这些内容每一项都值得单独写一篇文章今天先不展开。有一点我想特别强调环境上的问题永远是最容易解决的真正难的是坚持维护一个项目的习惯。把每次修改都用一句话记录清楚让提交历史像一本清晰的日记这个习惯比任何命令技巧都值钱。最后再分享一个小技巧如果你在操作过程中碰到了一个报错把报错信息原封不动复制到搜索引擎里搜通常都能找到前人的解决方案。Git 发展这么多年你踩过的坑大概率也被人踩过而且大概率已经有解了。不要怕报错报错是 Git 在告诉你它期望什么学会读报错你就学会了一半 Git。