Netlify部署HTML静态站点的基本流程教程

先说几个容易踩的坑。Netlify 这个事儿，说起来门槛不高，但卡住过不少人。尤其是第一次部署纯静态站点的时候，经常会碰上一堆 404、白屏，或者莫名其妙地跳转到 Netlify 默认欢迎页。其实多数问题都出在本地文件组织和路径引用这两个环节上，跟 Netlify 本身的稳定性没太大关系。

Netlify部署时找不到index.html怎么办

Netlify 识别一个静态站点的前提，是在发布目录里看到 index.html（或者 404.html）。如果找不到，就直接报“Page Not Found”或显示 Netlify 自带的那个欢迎页——这和站点内容无关，纯粹是 Netlify 不知道入口文件在哪里。

几个常见场景：

• 用 HTTrack 这类工具下载站点后，文件往往会被打包进子文件夹里（比如 mysite/），需要把里面的内容提到 ZIP 或仓库根目录。
• Windows 下文件名大小写不敏感，但 Netlify 运行在 Linux 环境。Index.html 或 INDEX.HTM 都不会被识别，必须是小写 index.html。
• 如果用了构建工具（比如 Astro、Jekyll），记得 publish 路径要指向生成后的目录（如 dist/ 或 _site/），而不是源码目录。

手动上传ZIP包失败的常见原因

拖放 ZIP 部署确实方便，但实际走一遍就会碰到一些暗坑——解压路径不对、页面空白或 404，往往就出在这几步上。

• ZIP 必须是“扁平结构”：index.html 必须直接在 ZIP 根层，不能嵌套在额外的文件夹里（比如 my-site/my-site/index.html 这种结构就要调整）。
• 隐藏文件或 macOS 的 .DS_Store 也可能干扰 Netlify 解析。建议用 zip -r site.zip * -x ".DS_Store" 来生成压缩包。
• 上传后别急着关页面。Netlify 解压和检测需要几秒钟，刷新太早可能会看到临时错误页。可以留意右上角的部署状态图标，变绿勾才算稳定。

用Git部署时build命令和publish目录怎么填

Netlify 能自动识别一部分框架（比如 Gatsby、Next.js），但对纯 HTML 项目或自定义构建流程，还是得手动指定 command 和 publish 参数，不然它猜不到你的意图。

• 纯静态站点（无构建步骤）：command 留空，publish 填 .（点号，表示根目录）。
• 使用 npm 构建（如 npm run build 输出到 dist/）：command 填 npm run build，publish 填 dist。
• 用 Jekyll：command 是 jekyll build，publish 是 _site；用 Astro 则是 astro build + dist。
• 所有路径都**不需要前导斜杠**。/dist 是错的，dist 才对。

部署后资源404或样式丢失

这个问题和 Netlify 本身几乎无关，问题在于 HTML、CSS、JS 中引用的相对路径没有对齐发布后的目录结构。换句话说，本地能跑，上传后就找不到文件了。

• 检查所有 这类路径。如果 CSS 文件实际在 assets/css/style.css，那 href 就得写成 assets/css/style.css。对不上就白屏。
• 图片路径同理。 要确保 images/logo.png 确实存在于 ZIP 或 Git 仓库的对应位置。
• 尽量避免绝对路径（如 /css/style.css），除非你设置了 baseURL 或 Netlify 的 _redirects 规则来兜底。
• 最直接的方法是打开浏览器开发者工具的 Network 标签页，看哪个文件返回 404，反向定位路径错在哪一层。这比猜要快得多。

Netlify 对纯静态站点足够友好，但它的自动化建立在“约定优于配置”的基础上——它不猜你想要什么，只严格按规则执行。所以，最常出问题的地方，其实不是部署操作本身，而是本地文件组织和路径引用这两个隐形环节。