Netlify 部署托管 GitHub Pages 静态网站

为什么用 Netlify 而不是 GitHub Pages

GitHub Pages 托管静态站免费好用，但对国内访问者有两个硬伤：一是 CDN 节点在境外，加载慢；二是它的域名解析不稳，时常打不开。自定义域名能改善一点但治不了根本。

Netlify 的优势在于它有自己的全球 CDN，且节点分布对国内相对友好。更重要的是它把「构建」也接管了——GitHub Pages 只托管静态文件，需要构建的项目（Vue、React、VitePress 这些）得自己配 CI 把产物推到 gh-pages 分支；Netlify 直接读源码仓库，在它的机器上跑构建命令，产物自动上线。省掉了整套 CI 配置。

免费额度对个人博客够用：每月 100GB 流量、300 分钟构建时间。还自带 HTTPS 证书（Let's Encrypt 自动申请续期）、分支预览（每个 PR 生成独立的预览地址）、重定向和 header 配置。

使用 netlify 发布自己的静态网站项目

打开 https://app.netlify.com/signup 注册账号，建议直接使用 GitHub 账号进行登录。

用 GitHub 账号登录能省掉后面的授权步骤，注册和仓库授权一次完成。

选择 github/gitlab，这时候会弹出授权登录的窗口，直接点击授权就可以。

下面两张图是注册页和授权确认页。授权时注意 Netlify 申请的权限范围——它需要读仓库内容和写 webhook（用来监听 push 事件触发构建）：

Netlify 注册页面，提供 GitHub、GitLab 等第三方账号登录入口

选择 github 或者 gitlab，以选择对应仓库中的代码

授权完成后进入选择代码源的页面，Netlify 会列出你有权限的仓库：

Netlify 中选择 Git 代码托管平台的界面，可选 GitHub、GitLab、Bitbucket

选择接受

这一步是确认授权 Netlify 访问哪些仓库。可以只授权单个仓库而不是全部——从最小权限原则出发，我一般只勾要部署的那个：

GitHub 中选择授权 Netlify 访问的仓库范围，可选全部仓库或指定仓库

选中需要发布的分支

选好仓库后配置构建。这一页有三个关键字段：分支（选哪个分支的代码，一般是 main 或 master）、Build command（构建命令，比如 npm run build）、Publish directory（产物目录，Vite 项目通常是 dist，VitePress 是 .vitepress/dist，Hexo 是 public）。

产物目录填错是最常见的失败原因，构建日志显示成功但访问 404，一般就是这里指偏了。纯 HTML 静态站不需要构建，Build command 留空、Publish directory 填 . 即可。

点击部署

点下去之后 Netlify 会拉代码、装依赖、跑构建。整个过程的日志能实时看到，构建失败时错误信息也在这里——本地能构建但 Netlify 上失败，最常见的原因是 Node 版本不一致（在环境变量里设 NODE_VERSION 指定）或者依赖没提交 lockfile：

编辑选中好的站点

部署成功后 Netlify 会分配一个随机的二级域名，形如 random-name-123456.netlify.app。这个名字是随机生成的，不好记，进站点设置里能改：

更改成自己想要使用的访问 url

在 Domain settings 里改站点名称，改完访问地址就变成 你的名字.netlify.app。名称是全平台唯一的，被占了就得换一个。

如果有自己的域名，在同一个页面点 Add custom domain 绑定，然后去域名服务商那里把 DNS 指向 Netlify（加 CNAME 记录指到 你的站点.netlify.app）。绑定后 Netlify 会自动申请 HTTPS 证书，几分钟内生效，不用自己折腾证书：

tip

以后只需要代码提交到 github 仓库，netlify 会自动部署

自动部署靠的是授权时装上的 webhook：push 到指定分支，GitHub 通知 Netlify，Netlify 拉最新代码重新构建上线。整个流程无需人工介入，写完文章 git push 就完事了。

几个实用配置

构建配置写进仓库。在项目根目录建 netlify.toml，把构建命令、产物目录、重定向规则都写进去，比在网页界面上点更好——配置进了版本控制，换仓库或者重建站点时直接复用：

[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

最后那段 redirects 是 SPA 项目必须的。前端路由的路径在服务器上没有对应文件，直接访问子路径会 404，这条规则把所有请求都回落到 index.html，交给前端路由处理。status = 200 而不是 301 很关键，它是内部重写不是跳转，URL 保持不变。

关掉不需要的分支部署。默认只部署主分支，但如果开了所有分支部署，每个功能分支都会消耗构建时间。免费额度 300 分钟不多，按需开启。

构建缓存。Netlify 会缓存 node_modules，第二次构建快很多。如果遇到依赖装错的诡异问题，在部署页面选 Clear cache and deploy site 强制重装。