部署问题排查

部署出问题是常态，这里列出最常见的问题和解决方案。

构建失败

依赖安装失败

症状：npm install 或 yarn install 报错

原因：

依赖版本冲突
网络问题
Node.js 版本不兼容

解决：

# 删除 node_modules 和锁文件
rm -rf node_modules package-lock.json

# 重新安装
npm install

# 或使用 yarn
rm -rf node_modules yarn.lock
yarn install

指定 Node.js 版本：

// package.json
{
  "engines": {
    "node": ">=18.0.0"
  }
}

构建命令失败

症状：npm run build 报错

原因：

TypeScript 类型错误
ESLint 错误
环境变量缺失

解决：

# 本地运行构建
npm run build

# 查看详细错误
npm run build -- --verbose

跳过类型检查（不推荐）：

// next.config.js
module.exports = {
  typescript: {
    ignoreBuildErrors: true,
  },
  eslint: {
    ignoreDuringBuilds: true,
  },
}

内存不足

症状：JavaScript heap out of memory

解决：

// package.json
{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

运行时错误

应用启动失败

症状：部署成功但应用无法访问

原因：

端口配置错误
启动命令错误
环境变量缺失

解决：

检查端口配置：

// server.js
const PORT = process.env.PORT || 3000
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`)
})

检查启动命令：

// package.json
{
  "scripts": {
    "start": "node server.js"
  }
}

环境变量未定义

症状：process.env.XXX is undefined

解决：

检查环境变量是否在平台配置
前端变量是否加了前缀（NEXT_PUBLIC_）
修改后是否重新部署

// 添加默认值
const apiUrl = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000'

数据库连接失败

症状：ECONNREFUSED 或 Connection timeout

原因：

数据库未启动
连接字符串错误
网络限制

解决：

检查连接字符串：

# 正确格式
postgresql://user:password@host:5432/dbname

# 检查是否能连接
psql $DATABASE_URL

检查网络：

# 测试连接
nc -zv host 5432

页面问题

404 错误

症状：部署后页面显示 404

原因：

路由配置错误
静态导出配置错误
文件路径大小写问题

解决：

检查路由：

// Next.js App Router
// app/about/page.js 对应 /about

检查静态导出：

// next.config.js
module.exports = {
  output: 'export', // 静态导出
  trailingSlash: true, // 添加尾部斜杠
}

样式丢失

症状：部署后样式不生效

原因：

CSS 文件路径错误
构建时未包含 CSS
CSP 策略限制

解决：

检查 CSS 导入：

// 确保导入了全局样式
import './globals.css'

检查构建输出：

# 查看构建产物
ls -la .next/static/css/

图片无法显示

症状：图片显示 404 或加载失败

原因：

图片路径错误
图片未包含在构建中
图片优化配置错误

解决：

使用正确的路径：

// Next.js
import Image from 'next/image'

// public 目录下的图片
<Image src="/logo.png" width={200} height={100} alt="Logo" />

// 外部图片需要配置域名
// next.config.js
module.exports = {
  images: {
    domains: ['example.com'],
  },
}

性能问题

页面加载慢

原因：

包体积太大
未启用缓存
未使用 CDN

解决：

分析包体积：

# Next.js
npm run build
# 查看输出的包大小

# 使用 Bundle Analyzer
npm install @next/bundle-analyzer

启用缓存：

// next.config.js
module.exports = {
  headers: async () => [
    {
      source: '/static/:path*',
      headers: [
        {
          key: 'Cache-Control',
          value: 'public, max-age=31536000, immutable',
        },
      ],
    },
  ],
}

API 响应慢

原因：

数据库查询慢
未使用索引
N+1 查询问题

解决：

添加数据库索引：

CREATE INDEX idx_user_email ON users(email);

使用查询优化：

// Prisma - 使用 include 避免 N+1
const users = await prisma.user.findMany({
  include: {
    posts: true,
  },
})

HTTPS 问题

证书错误

症状：浏览器显示"不安全"或证书错误

原因：

证书未生成
DNS 未正确配置
证书过期

解决：

检查 DNS：

dig example.com
nslookup example.com

重新生成证书：

# Let's Encrypt
sudo certbot renew --force-renewal

混合内容警告

症状：HTTPS 页面加载 HTTP 资源

解决：

将所有资源改为 HTTPS：

<!-- ❌ 错误 -->
<img src="http://example.com/image.jpg">

<!-- ✅ 正确 -->
<img src="https://example.com/image.jpg">

<!-- ✅ 或使用协议相对路径 -->
<img src="//example.com/image.jpg">

域名问题

DNS 未生效

症状：域名无法访问

原因：

DNS 记录配置错误
DNS 传播未完成

解决：

检查 DNS 记录：

dig example.com
# 应该看到正确的 A 或 CNAME 记录

等待 DNS 传播（最多 48 小时，通常几分钟）。

域名重定向循环

症状：浏览器显示"重定向次数过多"

原因：

HTTPS 重定向配置错误
CDN 和源站都配置了重定向

解决：

检查重定向配置：

// next.config.js
module.exports = {
  async redirects() {
    return [
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-forwarded-proto',
            value: 'http',
          },
        ],
        destination: 'https://example.com/:path*',
        permanent: true,
      },
    ]
  },
}

数据库问题

连接数耗尽

症状：too many connections

原因：

未使用连接池
连接未正确关闭

解决：

使用连接池：

// Prisma
const prisma = new PrismaClient({
  datasources: {
    db: {
      url: process.env.DATABASE_URL,
    },
  },
  // 配置连接池
  pool: {
    max: 10,
  },
})

迁移失败

症状：数据库迁移报错

解决：

查看迁移状态：

npx prisma migrate status

手动修复：

# 标记迁移为已应用
npx prisma migrate resolve --applied "migration_name"

# 或回滚
npx prisma migrate resolve --rolled-back "migration_name"

调试技巧

查看日志

Vercel

vercel logs

Railway

在 Railway 后台 → Deployments → 查看日志

Fly.io

flyctl logs

远程调试

// 添加详细日志
console.log('Environment:', process.env.NODE_ENV)
console.log('Database URL:', process.env.DATABASE_URL?.substring(0, 20))

本地复现

# 使用生产环境变量
NODE_ENV=production npm run build
NODE_ENV=production npm start

回滚部署

Vercel

# 查看部署历史
vercel ls

# 回滚到指定版本
vercel rollback [deployment-url]

Railway

在 Railway 后台 → Deployments → 选择之前的版本 → Redeploy

Fly.io

# 查看版本
flyctl releases

# 回滚
flyctl releases rollback

预防措施

1. 本地测试

部署前在本地运行生产构建：

npm run build
npm start