index.html必须位于项目根目录或public/子目录，Netlify仅在这两个位置查找，不递归扫描；其他路径如src/或dist/下的index.html均无效，否则部署后访问返回404。
index.html 必须在根目录或 public/ 下
Netlify 不会递归扫描整个项目找入口文件，它只认两个位置：index.html 在项目根目录，或者在 public/ 子目录里。其他路径比如 src/index.html、dist/html/home.html 都不会被自动识别。
常见错误现象：部署成功但访问时 404，控制台显示 “Page not found”，实际是 Netlify 根本没找到可服务的 index.html。
- 如果用 HTTrack 下载的网站，解压后直接检查是否能看到
index.html在最外层 - 不要重命名入口文件为
home.html或default.html—— Netlify 不做 fallback 查找 - 用 Git 部署时，确认
git status能看到index.html，且没被.gitignore意外排除
拖拽上传 vs GitHub 连接：选哪个更可靠
拖拽上传适合临时演示、单页 HTML 小工具，5 秒就能上线；但没版本记录、没法回滚、也不能自动更新。生产级站点必须走 Git（GitHub/GitLab/Bitbucket）。
容易踩的坑：
anything-to-html
下载
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- 新仓库默认分支是
main，但旧项目可能还是master—— Netlify 默认拉main，如果没手动改成master，就会部署空目录 - Git 提交时漏了
git add .，只提交了部分文件，导致 CSS/JS 加载失败或页面空白 - 压缩包上传时没解压干净（比如 macOS 的隐藏文件
.DS_Store占位），也可能干扰路径解析
部署后 404？先查这三处硬性条件
不是 Netlify 故障，而是静态托管的基本约束没满足：
-
href="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 站点完全不需要这个文件。只有遇到这些具体问题才值得加几行：
- 用
history.pushState的单页应用（SPA）：加[[redirects]] from = "/*" to = "/index.html" status = 200 - 强制 HTTPS：加
[[headers]] for = "/*"块 +Strict-Transport-Security头 - 让图片/CSS/JS 缓存更久：在
[[headers]]里配Cache-Control，避免每次刷新都重新下载
别为了“看起来专业”提前加配置 —— 多一行就多一个维护点，而 Netlify 对纯静态文件的默认行为已经足够健壮。
