六维教程

EdgeOne Makers 排障指南

部署过程中总会遇到各种问题，可能是构建失败、部署超时、页面访问异常等。这篇文章整理了常见的错误类型和排查方法，帮助你快速定位和解决问题。

构建阶段错误

构建阶段是最容易出问题的环节，因为涉及到代码编译、依赖安装等复杂过程。

依赖安装失败

错误表现

npm ERR! code ERESOLVE
npm ERR! Could not resolve dependency

可能原因

  1. 依赖版本冲突
  2. 网络问题导致下载失败
  3. 私有包没有配置认证信息

排查方法

  1. 查看构建日志，找到具体的错误包
  2. 检查 package.json 中的版本约束
  3. 尝试本地清理缓存后重新安装rm -rf node_modules package-lock.json && npm install

解决方案

{
  "overrides": {
    "problematic-package": "compatible-version"
  }
}

或者使用 --legacy-peer-deps 参数

build:
  command: npm install --legacy-peer-deps && npm run build

构建命令失败

错误表现

npm ERR! Missing script: build

可能原因

  1. package.json 中没有定义 build 脚本
  2. 脚本名称写错（比如写成了 build:prod）
  3. 使用的框架不支持标准构建命令

排查方法

  1. 检查 package.json 的 scripts 字段
  2. 确认框架的官方构建命令
  3. 查看项目是否有自定义构建配置

解决方案
在 package.json 中添加正确的构建脚本

{
  "scripts": {
    "build": "vite build"
  }
}

或者在项目配置中指定自定义构建命令。

内存溢出

错误表现

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed
JavaScript heap out of memory

可能原因

  1. 项目太大，构建时内存不够
  2. 某些插件或工具内存泄漏
  3. 构建环境的内存限制太低

排查方法

  1. 查看构建日志中的内存使用情况
  2. 检查是否有大型文件或复杂操作
  3. 尝试本地构建，看是否也有问题

解决方案
在项目配置中增加内存限制

build:
  environment:
    NODE_OPTIONS: --max-old-space-size=4096

部署阶段错误

部署阶段的问题通常和网络、配置相关。

部署超时

错误表现

Deployment timed out after 300 seconds

可能原因

  1. 构建产物太大
  2. 网络不稳定
  3. 平台临时故障

排查方法

  1. 检查构建产物的大小（通常限制在 100MB 以内）
  2. 查看平台状态页面，确认是否有故障
  3. 尝试重新部署

解决方案

  1. 优化构建产物，删除不必要的文件
  2. 使用 .edgeoneignore 排除大文件
.git
node_modules
*.log
  1. 等待几分钟后重试

域名解析失败

错误表现

DNS resolution failed for custom-domain.com

可能原因

  1. CNAME 或 A 记录配置错误
  2. DNS 还没有生效（需要 24-48 小时）
  3. 域名所有权验证失败

排查方法

  1. 使用 dig 或 nslookup 检查 DNS 记录
  2. 确认 CNAME 指向是否正确
  3. 检查 TXT 验证记录是否添加

解决方案

# 检查 CNAME 记录
dig CNAME your-domain.com

# 检查 TXT 记录
dig TXT _edgeone-verify.your-domain.com

确认 DNS 配置正确后，耐心等待生效。

SSL 证书申请失败

错误表现

SSL certificate provisioning failed

可能原因

  1. 域名解析还没有生效
  2. 域名被防火墙拦截
  3. Let’s Encrypt 限流

排查方法

  1. 确认域名已经可以正常访问
  2. 检查 DNS 解析是否正确指向 EdgeOne
  3. 查看证书申请日志

解决方案

  1. 等待 DNS 完全生效后再申请证书
  2. 如果是限流问题，等待 1 小时后重试
  3. 联系技术支持

运行时错误

部署成功后，网站运行中也可能出现问题。

页面 404

错误表现访问网站返回 404 Not Found

可能原因

  1. 构建产物路径配置错误
  2. 单页应用（SPA）路由配置问题
  3. 文件结构不符合预期

排查方法

  1. 检查项目配置中的输出目录
  2. 查看构建产物是否包含 index.html
  3. 确认框架的路由模式

解决方案
对于单页应用，添加重定向规则

{
  "redirects": [
    {
      "source": "/*",
      "destination": "/index.html",
      "status": 200
    }
  ]
}

环境变量未生效

错误表现代码中读取的环境变量是 undefined

可能原因

  1. 变量名拼写错误
  2. 没有重新部署
  3. 变量作用域配置错误

排查方法

  1. 检查环境变量名称是否一致
  2. 确认是否已经触发新的部署
  3. 查看变量是构建时还是运行时变量

解决方案

// 正确读取环境变量
const apiKey = process.env.API_KEY;

// 检查是否定义
console.log('API_KEY:', process.env.API_KEY);

修改环境变量后，一定要重新部署才能生效。

函数执行错误

错误表现

Error: Function execution failed

可能原因

  1. 函数代码有语法错误
  2. 依赖没有正确安装
  3. 超时或内存不足

排查方法

  1. 查看函数执行日志
  2. 本地测试函数是否正常
  3. 检查函数的资源限制配置

解决方案

// 添加错误处理
export default async function handler(req, res) {
  try {
    const result = await processData(req.body);
    res.json({ success: true, data: result });
  } catch (error) {
    console.error('Function error:', error);
    res.status(500).json({ 
      success: false, 
      error: error.message 
    });
  }
}

日志查看

日志是排查问题的关键，EdgeOne Makers 提供了多层次的日志查看方式。

构建日志

查看方式项目控制台 → 部署记录 → 点击部署 ID → 构建日志

包含内容

  • 依赖安装过程
  • 构建命令输出
  • 错误信息和堆栈跟踪

使用技巧

  1. 使用 Ctrl+F 搜索关键词（如 error、failed）
  2. 关注最后几行，通常是错误总结
  3. 对比成功部署的日志，找差异

运行时日志

查看方式项目控制台 → 日志

包含内容

  • 请求日志（访问时间、路径、状态码）
  • 函数执行日志
  • 错误日志

使用技巧

  1. 按时间筛选，定位问题发生的时间段
  2. 按状态码筛选，快速找到 4xx 和 5xx 错误
  3. 导出日志进行离线分析

实时日志

查看方式CLI 工具 edgeone logs --follow

使用场景

  • 部署后实时监控
  • 调试运行时问题
  • 观察性能表现

示例

# 实时查看日志
edgeone logs --follow

# 过滤错误日志
edgeone logs --follow | grep ERROR

# 查看最近 100 行
edgeone logs --tail 100

常见问题排查清单

部署失败排查

  • 检查构建日志，找到具体错误
  • 本地运行构建命令，看是否成功
  • 检查 Node.js 版本是否匹配
  • 确认依赖是否完整
  • 查看平台状态页面

网站无法访问排查

  • 检查域名解析是否正确
  • 确认 SSL 证书是否有效
  • 查看项目状态是否为 Active
  • 检查自定义域名配置
  • 尝试访问默认域名

性能问题排查

  • 检查构建产物大小
  • 分析首屏加载时间
  • 查看资源缓存配置
  • 检查图片是否优化
  • 使用浏览器开发者工具分析

获取帮助

如果自己无法解决问题，可以通过以下渠道获取帮助

渠道 说明 响应时间
官方文档 详细的功能说明和示例 即时
社区论坛 其他用户的经验分享 几小时到 1 天
技术支持 提交工单，专业人员解答 1-2 个工作日
企业支持 购买的企业享受专属服务 根据 SLA

提交工单时提供

  1. 项目名称和 ID
  2. 部署 ID（如果是部署问题）
  3. 错误截图或日志
  4. 复现步骤
  5. 期望的结果

速查卡片

关键点 说明
构建错误 检查依赖版本、构建命令、内存限制
部署超时 优化产物大小、检查网络、查看平台状态
域名问题 验证 DNS 配置、等待生效、检查证书
运行时错误 查看日志、检查环境变量、确认路由配置
日志查看 构建日志、运行时日志、实时日志三种方式
排查清单 按步骤逐一检查，避免遗漏
获取帮助 文档、社区、工单、企业支持四个渠道
上一篇
EdgeOne Makers 消息通知
下一篇
EdgeOne Makers 常见问题