故障排查 #

构建问题 #

构建失败常见原因 #

原因	解决方案
依赖安装失败	检查 package.json
构建命令错误	验证构建命令
内存不足	优化构建配置
超时	减少构建步骤

问题1：依赖安装失败 #

症状：

text

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

解决方案：

bash

# 方案1：使用 legacy peer deps
npm install --legacy-peer-deps

# 方案2：删除 lock 文件重新安装
rm -rf node_modules package-lock.json
npm install

netlify.toml 配置：

toml

[build.environment]
  NPM_FLAGS = "--legacy-peer-deps"

问题2：构建命令找不到 #

症状：

text

"build" script not found

解决方案：

检查 package.json：

json

{
  "scripts": {
    "build": "your-build-command"
  }
}

问题3：内存不足 #

症状：

text

JavaScript heap out of memory

解决方案：

toml

[build.environment]
  NODE_OPTIONS = "--max_old_space_size=4096"

问题4：构建超时 #

症状：

text

Build exceeded maximum allowed runtime

解决方案：

优化构建速度
减少依赖
使用缓存

yaml

# GitHub Actions 缓存
- name: Cache dependencies
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

问题5：环境变量未生效 #

症状：

text

ReferenceError: process.env.XXX is not defined

解决方案：

检查环境变量名称
确认变量已设置
前端变量需要正确前缀

bash

# React
REACT_APP_API_URL=xxx

# Vite
VITE_API_URL=xxx

# Next.js
NEXT_PUBLIC_API_URL=xxx

部署问题 #

问题1：部署成功但页面空白 #

可能原因：

路由配置错误
资源路径错误
JavaScript 错误

排查步骤：

检查浏览器控制台错误
检查网络请求
验证构建输出

解决方案：

toml

# SPA 路由配置
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

问题2：资源 404 #

症状：

text

GET https://example.com/assets/main.js 404

排查步骤：

检查 publish 目录配置
验证文件是否存在于构建输出
检查文件路径大小写

解决方案：

toml

[build]
  publish = "dist"  # 确认正确的输出目录

问题3：CSS 未加载 #

可能原因：

文件路径错误
MIME 类型错误
CSP 限制

解决方案：

toml

[[headers]]
  for = "/*.css"
  [headers.values]
    Content-Type = "text/css"

问题4：API 请求 CORS 错误 #

症状：

text

Access to fetch at 'xxx' from origin 'xxx' has been blocked by CORS policy

解决方案：

toml

[[headers]]
  for = "/api/*"
  [headers.values]
    Access-Control-Allow-Origin = "*"
    Access-Control-Allow-Methods = "GET, POST, OPTIONS"

域名问题 #

问题1：域名无法访问 #

排查步骤：

bash

# 检查 DNS 解析
dig example.com

# 检查 A 记录
dig example.com A +short

# 检查 CNAME
dig www.example.com CNAME +short

解决方案：

确保 DNS 配置正确：

text

A 记录: @ → 75.2.60.5
CNAME: www → your-site.netlify.app

问题2：SSL 证书未生效 #

症状：

text

Your connection is not secure

排查步骤：

检查域名是否已验证
等待证书申请完成
检查 DNS 配置

解决方案：

text

Site settings → Domain management → HTTPS → Verify DNS configuration

问题3：域名重定向循环 #

症状：

text

Too many redirects

排查步骤：

检查 netlify.toml 重定向规则
确认主域名设置
清除浏览器缓存

解决方案：

toml

# 确保没有循环重定向
[[redirects]]
  from = "https://example.com/*"
  to = "https://www.example.com/:splat"
  status = 301
  force = true

函数问题 #

问题1：函数 500 错误 #

排查步骤：

查看函数日志
检查函数代码
验证环境变量

bash

netlify functions:log function-name

问题2：函数超时 #

症状：

text

Task timed out after 10.00 seconds

解决方案：

优化函数代码
减少外部调用
升级方案增加超时时间

问题3：函数依赖问题 #

症状：

text

Cannot find module 'xxx'

解决方案：

确保依赖在 package.json 中：

json

{
  "dependencies": {
    "xxx": "^1.0.0"
  }
}

或使用 bundled 函数：

text

netlify/functions/
└── my-function/
    ├── index.js
    └── package.json

问题4：函数环境变量未生效 #

解决方案：

toml

[build.environment]
  MY_VAR = "value"

或在控制台设置环境变量。

表单问题 #

问题1：表单提交不显示 #

排查步骤：

检查表单属性
验证表单名称
检查垃圾邮件过滤

解决方案：

html

<form name="contact" method="POST" data-netlify="true">
  <!-- 确保有 name 和 data-netlify 属性 -->
</form>

问题2：React 表单不工作 #

解决方案：

添加隐藏字段：

jsx

<form name="contact" method="POST" data-netlify="true">
  <input type="hidden" name="form-name" value="contact" />
  <!-- 其他字段 -->
</form>

问题3：表单提交 404 #

解决方案：

确保表单在构建时被 Netlify 识别：

表单必须在静态 HTML 中
或使用 JavaScript 提交

性能问题 #

问题1：加载速度慢 #

排查步骤：

使用 PageSpeed Insights 分析
检查资源大小
查看网络请求

解决方案：

toml

# 启用缓存
[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

问题2：函数响应慢 #

解决方案：

复用数据库连接
减少外部 API 调用
使用缓存

javascript

let cachedData

exports.handler = async () => {
  if (!cachedData) {
    cachedData = await fetchData()
  }
  return { body: JSON.stringify(cachedData) }
}

调试工具 #

本地调试 #

bash

# 启动本地开发环境
netlify dev

# 查看函数日志
netlify functions:log function-name --tail

构建调试 #

bash

# 本地构建测试
netlify build --dry-run

网络调试 #

bash

# 检查 DNS
dig example.com

# 检查 HTTP 头
curl -I https://example.com

# 检查 SSL
openssl s_client -connect example.com:443

日志分析 #

text

Deploys → 选择部署 → Deploy log

查看详细构建日志。

获取帮助 #

文档资源 #

联系支持 #

text

Help → Contact support

付费方案提供优先支持。

提交问题建议 #

提供以下信息：

站点 URL
部署 ID
错误信息
复现步骤

最佳实践 #

1. 使用版本控制 #

所有配置文件提交到 Git
记录配置变更

2. 监控告警 #

配置部署失败通知
监控关键指标

3. 定期检查 #

检查构建日志
审查依赖更新
清理无用资源

4. 文档化 #

记录常见问题解决方案
维护运维手册

恭喜完成！ #

你已经完成了 Netlify 完全指南的学习！现在你已经掌握了：

✅ Netlify 基础概念
✅ 项目部署配置
✅ 域名管理
✅ 功能特性使用
✅ 高级主题应用
✅ 故障排查技巧

继续实践，成为 Netlify 专家！