aibot88 Next.js 项目服务器部署技能
技能描述
自动化部署 Next.js 项目到 Linux 服务器（Ubuntu/Debian），支持国内服务器 GitHub 镜像加速。
适用场景
- Next.js 14+ App Router 项目
- 使用 SQLite 数据库（better-sqlite3）
- 使用 NextAuth.js 认证
- 需要部署到腾讯云/阿里云等国内服务器
前置条件
- 服务器 SSH 访问权限（密钥或密码）
- 服务器 IP 地址
- 项目已推送到 GitHub 仓库
部署流程
1. 连接服务器并安装环境
# SSH 连接
ssh -i ~/.ssh/your-key.pem ubuntu@YOUR_SERVER_IP
# 安装 Node.js 18
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs build-essential
# 安装 PM2
sudo npm install -g pm2
2. 克隆项目（国内服务器使用镜像）
# 方式一：直接克隆（海外服务器）
git clone https://github.com/YOUR_REPO.git talentgraph
# 方式二：使用镜像（国内服务器）
git clone https://ghfast.top/https://github.com/YOUR_REPO.git talentgraph
cd talentgraph
3. 安装依赖
npm install
npm install --save-dev @types/better-sqlite3
4. 配置环境变量
cat > .env << 'EOF'
# NextAuth 配置
NEXTAUTH_URL=http://YOUR_SERVER_IP:3000
NEXTAUTH_SECRET=your-random-secret-key
# AI 服务配置
DEEPSEEK_API_KEY=your-deepseek-key
OPENAI_API_KEY=your-openai-key
EOF
5. 构建项目
npm run build
6. 启动服务
pm2 start npm --name talentgraph -- start
pm2 save
7. 开放防火墙端口
# Ubuntu UFW
sudo ufw allow 3000/tcp
# 或在云服务商控制台安全组中放行 3000 端口
常见构建问题及解决方案
问题 1: GitHub clone 超时
原因: 国内网络访问 GitHub 不稳定
解决方案: 使用镜像加速
git clone https://ghfast.top/https://github.com/YOUR_REPO.git
问题 2: trustHost 属性报错
错误信息: Object literal may only specify known properties, and 'trustHost' does not exist in type 'NextAuthOptions'.
原因: NextAuth v4 不支持 trustHost 属性（这是 v5 的 API）
解决方案: 移除 trustHost: true 配置
const handler = NextAuth({
secret: process.env.NEXTAUTH_SECRET,
- trustHost: true,
providers: [...]
})
问题 3: Property 'role' does not exist on type 'User'
原因: NextAuth 默认的 User 类型没有 role 字段
解决方案: 使用类型断言绕过
// 在 authorize 回调中
return {
id: user.id,
name: user.name,
email: user.email,
role: user.role // 直接返回
}
// 在 jwt 回调中
async jwt({ token, user }) {
if (user) {
token.userId = user.id
;(token as any).role = (user as any).role
}
return token
}
// 在 session 回调中
async session({ session, token }) {
if (session.user) {
(session.user as any).id = (token as any).userId
;(session.user as any).role = (token as any).role
}
return session
}
问题 4: Request is not assignable to NextRequest
原因: Next.js App Router 的 route handler 要求使用 NextRequest 类型
解决方案: 所有 API route 文件使用 NextRequest
- import { NextResponse } from 'next/server'
+ import { NextResponse, NextRequest } from 'next/server'
- export async function GET(req: Request) {
+ export async function GET(req: NextRequest) {
问题 5: Cannot find module 'better-sqlite3' 类型错误
原因: 缺少 TypeScript 类型声明
解决方案:
npm install --save-dev @types/better-sqlite3
问题 6: pdfjs-dist 构建失败
错误信息: Failed to parse source file... Syntax Error
原因: pdfjs-dist 的 worker 文件太大，SWC 无法解析
解决方案: 改用 CDN 加载 worker
- pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
- 'pdfjs-dist/build/pdf.worker.min.mjs',
- import.meta.url
- ).href
+ pdfjsLib.GlobalWorkerOptions.workerSrc = `https://cdnjs.cloudflare.com/ajax/libs/pdf.js/${pdfjsLib.version}/pdf.worker.min.mjs`
问题 7: NEXTAUTH_URL 端口错误
原因: .env 文件中的 NEXTAUTH_URL 端口与实际运行端口不一致
解决方案: 确保 NEXTAUTH_URL 与服务器实际端口一致
# 正确
NEXTAUTH_URL=http://124.222.221.3:3000
# 错误（端口不匹配）
NEXTAUTH_URL=http://124.222.221.3:3003
部署检查清单
- Node.js 18+ 已安装 (
node -v) - PM2 已安装并配置开机自启 (
pm2 startup) -
.env文件已创建 -
NEXTAUTH_URL指向正确的服务器地址和端口 - 防火墙/安全组已放行 3000 端口
-
npm run build构建成功 - PM2 进程运行正常 (
pm2 status) - 服务可访问 (
curl http://localhost:3000)
常用运维命令
# 查看服务状态
pm2 status
# 查看日志
pm2 logs talentgraph
# 重启服务
pm2 restart talentgraph
# 停止服务
pm2 stop talentgraph
# 更新部署
cd ~/talentgraph
git pull origin master
npm run build
pm2 restart talentgraph
经验总结
国内服务器部署优先使用镜像: GitHub 直连在国内服务器上非常不稳定，
ghfast.top镜像可以大幅提高克隆成功率。NextAuth v4 类型问题: NextAuth v4 的 TypeScript 类型定义不够完善，扩展
User和Session类型时经常需要as any绕过。App Router 类型要求严格: 所有 route handler 必须使用
NextRequest，否则类型检查会失败。better-sqlite3 需要编译环境: 服务器上需要安装
build-essential和 Python 才能编译原生模块。环境变量必须正确配置:
NEXTAUTH_URL必须与实际访问地址一致，否则会导致登录后跳转错误。云服务商安全组: 除了服务器防火墙，还需要在云服务商控制台的安全组中放行端口。