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文件意外排除。

拖拽上传与Git连接：如何选择更可靠

两种部署方式各有适用场景。拖拽上传适合临时演示或快速分享单个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.toml，否则Netlify默认不会进行前端路由重写。
• 自定义域名配置不全：绑定了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的默认行为已足够智能和健壮。

仅当遇到以下具体需求时，才值得添加配置：

• 单页应用需要路由支持：若使用Vue Router、React Router等基于history.pushState的客户端路由，需添加重定向规则，使所有非文件请求回落到index.html：

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

• 强制HTTPS：如需增强安全性，可配置HTTP严格传输安全头。
• 优化缓存策略：若希望图片、CSS、JS等静态资源在用户浏览器中缓存更长时间，减少重复下载，可在[[headers]]部分配置Cache-Control。

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