手把手教你将HTML静态网页部署到Netlify

将静态网页部署到Netlify，听起来不难，但新手常踩不少坑。部署成功却返回404，这种“薛定谔的部署”最让人头疼。问题通常出在几个关键条件上，今天我们就详细拆解这些要点。

index.html 必须位于根目录或 public/ 目录下

这是第一条，也是最核心的规则。Netlify不会像侦探一样到处搜索入口文件，它只认两个固定位置：要么是项目根目录下的index.html，要么是public/子目录里的index.html。除此之外，像src/index.html或dist/html/home.html这类路径，Netlify会直接忽略。

所以，当你看到部署状态显示“Published”，但访问站点却显示“Page not found”时，第一反应应该是：Netlify是不是没找到我的index.html？

• 如果你是用HTTrack这类工具下载的整站，解压后第一件事，就是检查index.html是否位于最外层目录。
• 千万不要把入口文件改成home.html或default.html，Netlify没有自动回退查找的机制。
• 通过Git部署时，用git status确认一下index.html是否在待提交列表中，并且没有被.gitignore文件意外排除。

拖拽上传 vs GitHub 连接：哪种方式更可靠

两种方法各有适用场景。拖拽上传（Drag and Drop）适合临时演示、快速分享一个HTML小工具，几乎能做到“秒上线”。但它没有版本记录，无法回滚，也不能自动更新，不适合正式项目。

生产级站点，还是推荐走Git路线（连接GitHub、GitLab或Bitbucket）。不过，这里也有几个常见的“坑”：

• 分支名不匹配：现在新仓库默认分支是main，但很多老项目仍在使用master。Netlify默认拉取main分支，如果你没在设置里手动改为master，它部署的可能就是一个空目录。
• 提交不完整：git commit之前忘了git add .，只提交了HTML，遗漏了CSS或JS文件，结果就是页面样式错乱或功能失效。
• 压缩包“杂质”：上传ZIP包时，如果没解压干净（比如残留了macOS的隐藏文件.DS_Store），有时也会干扰Netlify对项目结构的正确解析。

部署后 404？先检查这三处硬性条件

排除了入口文件问题，访问还是404？那大概率是下面这三个静态托管的基本约束没满足：

• 相对路径必须真实存在：如果你的页面里有href="pages/about.html"这样的链接，那么pages/about.html这个文件必须真实存在于部署后的站点中。Netlify默认不会做前端路由的重写，除非你额外配置了netlify.toml。
• 自定义域名配置不全：绑定了www.yoursite.com，但DNS缺少对应的CNAME记录，或者在Netlify控制台没有点击「Verify domain」完成验证，域名状态会一直卡在“pending”。这时候访问，自然无法正确跳转。
• 资源引用路径错误：这是经典错误。代码里写的是绝对路径/css/style.css，但实际文件却放在styles/style.css目录下。浏览器会严格按照/css/style.css去请求，结果就是404。

什么情况下必须添加 netlify.toml

很多朋友觉得加个配置文件显得专业，其实对于90%的纯HTML/CSS/JS静态站点来说，完全不需要netlify.toml。Netlify的默认行为已经足够智能和健壮。

只有遇到下面这些具体需求时，才值得你动手添加几行配置：

• 单页应用（SPA）需要路由支持：如果你用了Vue Router、React Router等基于history.pushState的客户端路由，就需要添加一个重定向规则，让所有非文件请求都回落到index.html：

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

• 强制HTTPS：想要更安全，可以配置HTTP严格传输安全头（HSTS）。
• 优化缓存策略：想让图片、CSS、JS这些静态资源在用户浏览器里缓存得更久，减少重复下载，可以在[[headers]]里配置Cache-Control。

记住一个原则：配置不是勋章，多一行就多一个潜在的维护点。从简开始，按需添加，才是更稳妥的做法。