Next.js 中使用 MongoDB 完整指南

1. 安裝依賴

npm install mongodb
# 或者使用 mongoose（ODM）
npm install mongoose

2. 數據庫連接配置

使用原生 MongoDB 驅動

創建 lib/mongodb.js 文件：

import { MongoClient } from 'mongodb'const uri = process.env.MONGODB_URI
const options = {}let client
let clientPromiseif (process.env.NODE_ENV === 'development') {// 開發環境中使用全局變量避免重復連接if (!global._mongoClientPromise) {client = new MongoClient(uri, options)global._mongoClientPromise = client.connect()}clientPromise = global._mongoClientPromise
} else {// 生產環境中每次創建新連接client = new MongoClient(uri, options)clientPromise = client.connect()
}export default clientPromise

環境變量 .env.local：

MONGODB_URI=mongodb://localhost:27017/myapp
# 或者 MongoDB Atlas
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/database

3. API 路由中的基本操作

創建基礎的數據庫操作函數

創建 lib/db.js：

import clientPromise from './mongodb'export async function connectToDatabase() {const client = await clientPromiseconst db = client.db('myapp') // 數據庫名稱return { client, db }
}

4. 增加數據（Create）

插入單條記錄

創建 pages/api/users/create.js：

import { connectToDatabase } from '../../../lib/db'export default async function handler(req, res) {if (req.method !== 'POST') {return res.status(405).json({ message: 'Method not allowed' })}try {const { db } = await connectToDatabase()const collection = db.collection('users')// 插入單條記錄const newUser = {name: req.body.name,email: req.body.email,age: req.body.age,createdAt: new Date()}const result = await collection.insertOne(newUser)res.status(201).json({success: true,insertedId: result.insertedId,data: { ...newUser, _id: result.insertedId }})} catch (error) {res.status(500).json({ success: false, error: error.message })}
}

使用示例：

// 前端調用
const createUser = async () => {const response = await fetch('/api/users/create', {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({name: 'John Doe',email: 'john@example.com',age: 30})})const result = await response.json()console.log(result)
}

插入多條記錄

創建 pages/api/users/create-many.js：

import { connectToDatabase } from '../../../lib/db'export default async function handler(req, res) {if (req.method !== 'POST') {return res.status(405).json({ message: 'Method not allowed' })}try {const { db } = await connectToDatabase()const collection = db.collection('users')// 插入多條記錄const users = req.body.users.map(user => ({...user,createdAt: new Date()}))const result = await collection.insertMany(users)res.status(201).json({success: true,insertedCount: result.insertedCount,insertedIds: result.insertedIds})} catch (error) {res.status(500).json({ success: false, error: error.message })}
}

5. 查詢數據（Read）

查詢所有記錄

創建 pages/api/users/index.js：

import { connectToDatabase } from '../../../lib/db'export default async function handler(req, res) {if (req.method !== 'GET') {return res.status(405).json({ message: 'Method not allowed' })}try {const { db } = await connectToDatabase()const collection = db.collection('users')// 查詢所有記錄const users = await collection.find({}).toArray()res.status(200).json({success: true,count: users.length,data: users})} catch (error) {res.status(500).json({ success: false, error: error.message })}
}

查詢單條記錄

創建 pages/api/users/[id].js：

import { connectToDatabase } from '../../../lib/db'
import { ObjectId } from 'mongodb'export default async function handler(req, res) {const { id } = req.queryif (req.method === 'GET') {try {const { db } = await connectToDatabase()const collection = db.collection('users')// 通過 _id 查詢單條記錄const user = await collection.findOne({ _id: new ObjectId(id) })if (!user) {return res.status(404).json({ success: false, message: 'User not found' })}res.status(200).json({success: true,data: user})} catch (error) {res.status(500).json({ success: false, error: error.message })}}
}

條件查詢

創建 pages/api/users/search.js：

import { connectToDatabase } from '../../../lib/db'export default async function handler(req, res) {if (req.method !== 'GET') {return res.status(405).json({ message: 'Method not allowed' })}try {const { db } = await connectToDatabase()const collection = db.collection('users')const { name, email, minAge, maxAge, page = 1, limit = 10 } = req.query// 構建查詢條件let query = {}// 模糊查詢名稱if (name) {query.name = { $regex: name, $options: 'i' }}// 精確查詢郵箱if (email) {query.email = email}// 年齡范圍查詢if (minAge || maxAge) {query.age = {}if (minAge) query.age.$gte = parseInt(minAge)if (maxAge) query.age.$lte = parseInt(maxAge)}// 分頁const skip = (parseInt(page) - 1) * parseInt(limit)// 執行查詢const users = await collection.find(query).sort({ createdAt: -1 }) // 按創建時間倒序.skip(skip).limit(parseInt(limit)).toArray()// 獲取總數const total = await collection.countDocuments(query)res.status(200).json({success: true,data: users,pagination: {page: parseInt(page),limit: parseInt(limit),total,pages: Math.ceil(total / parseInt(limit))}})} catch (error) {res.status(500).json({ success: false, error: error.message })}
}

查詢特定字段

創建 pages/api/users/names.js：

import { connectToDatabase } from '../../../lib/db'export default async function handler(req, res) {if (req.method !== 'GET') {return res.status(405).json({ message: 'Method not allowed' })}try {const { db } = await connectToDatabase()const collection = db.collection('users')// 只查詢 name 和 email 字段，排除 _idconst users = await collection.find({}, { projection: { name: 1, email: 1, _id: 0 } }).toArray()res.status(200).json({success: true,data: users})} catch (error) {res.status(500).json({ success: false, error: error.message })}
}

6. 更新數據（Update）

更新單條記錄

在 pages/api/users/[id].js 中添加 PUT 方法：

import { connectToDatabase } from '../../../lib/db'
import { ObjectId } from 'mongodb'export default async function handler(req, res) {const { id } = req.queryif (req.method === 'PUT') {try {const { db } = await connectToDatabase()const collection = db.collection('users')const updateData = {...req.body,updatedAt: new Date()}// 移除不能更新的字段delete updateData._iddelete updateData.createdAt// 更新單條記錄const result = await collection.updateOne({ _id: new ObjectId(id) },{ $set: updateData })if (result.matchedCount === 0) {return res.status(404).json({ success: false, message: 'User not found' })}// 返回更新后的數據const updatedUser = await collection.findOne({ _id: new ObjectId(id) })res.status(200).json({success: true,modifiedCount: result.modifiedCount,data: updatedUser})} catch (error) {res.status(500).json({ success: false, error: error.message })}}
}

更新多條記錄

創建 pages/api/users/update-many.js：

import { connectToDatabase } from '../../../lib/db'export default async function handler(req, res) {if (req.method !== 'PUT') {return res.status(405).json({ message: 'Method not allowed' })}try {const { db } = await connectToDatabase()const collection = db.collection('users')const { filter, update } = req.body// 批量更新記錄const result = await collection.updateMany(filter,{ $set: {...update,updatedAt: new Date()}})res.status(200).json({success: true,matchedCount: result.matchedCount,modifiedCount: result.modifiedCount})} catch (error) {res.status(500).json({ success: false, error: error.message })}
}

使用示例：

// 將所有年齡小于18的用戶狀態設為未成年
const updateMinors = async () => {const response = await fetch('/api/users/update-many', {method: 'PUT',headers: { 'Content-Type': 'application/json' },body: JSON.stringify({filter: { age: { $lt: 18 } },update: { status: 'minor' }})})const result = await response.json()console.log(result)
}

7. 刪除數據（Delete）

刪除單條記錄

在 pages/api/users/[id].js 中添加 DELETE 方法：

export default async function handler(req, res) {const { id } = req.queryif (req.method === 'DELETE') {try {const { db } = await connectToDatabase()const collection = db.collection('users')// 刪除單條記錄const result = await collection.deleteOne({ _id: new ObjectId(id) })if (result.deletedCount === 0) {return res.status(404).json({ success: false, message: 'User not found' })}res.status(200).json({success: true,deletedCount: result.deletedCount,message: 'User deleted successfully'})} catch (error) {res.status(500).json({ success: false, error: error.message })}}
}

刪除多條記錄

創建 pages/api/users/delete-many.js：

import { connectToDatabase } from '../../../lib/db'export default async function handler(req, res) {if (req.method !== 'DELETE') {return res.status(405).json({ message: 'Method not allowed' })}try {const { db } = await connectToDatabase()const collection = db.collection('users')const { filter } = req.body// 批量刪除記錄const result = await collection.deleteMany(filter)res.status(200).json({success: true,deletedCount: result.deletedCount,message: `${result.deletedCount} users deleted successfully`})} catch (error) {res.status(500).json({ success: false, error: error.message })}
}

8. 高級查詢操作

聚合查詢

創建 pages/api/users/statistics.js：

import { connectToDatabase } from '../../../lib/db'export default async function handler(req, res) {if (req.method !== 'GET') {return res.status(405).json({ message: 'Method not allowed' })}try {const { db } = await connectToDatabase()const collection = db.collection('users')// 聚合查詢示例const statistics = await collection.aggregate([{$group: {_id: null,totalUsers: { $sum: 1 },averageAge: { $avg: '$age' },minAge: { $min: '$age' },maxAge: { $max: '$age' }}}]).toArray()// 按年齡分組統計const ageGroups = await collection.aggregate([{$group: {_id: {$switch: {branches: [{ case: { $lt: ['$age', 18] }, then: 'minor' },{ case: { $lt: ['$age', 65] }, then: 'adult' },{ case: { $gte: ['$age', 65] }, then: 'senior' }],default: 'unknown'}},count: { $sum: 1 }}}]).toArray()res.status(200).json({success: true,data: {statistics: statistics[0],ageGroups}})} catch (error) {res.status(500).json({ success: false, error: error.message })}
}

文本搜索

創建 pages/api/users/text-search.js：

import { connectToDatabase } from '../../../lib/db'export default async function handler(req, res) {if (req.method !== 'GET') {return res.status(405).json({ message: 'Method not allowed' })}try {const { db } = await connectToDatabase()const collection = db.collection('users')const { q } = req.query // 搜索關鍵詞if (!q) {return res.status(400).json({ success: false, message: 'Search query required' })}// 首先需要創建文本索引// await collection.createIndex({ name: 'text', email: 'text' })// 執行文本搜索const users = await collection.find({ $text: { $search: q } }).sort({ score: { $meta: 'textScore' } }).toArray()res.status(200).json({success: true,query: q,count: users.length,data: users})} catch (error) {res.status(500).json({ success: false, error: error.message })}
}

9. 在組件中使用

React 組件示例

// components/UserList.js
import { useState, useEffect } from 'react'export default function UserList() {const [users, setUsers] = useState([])const [loading, setLoading] = useState(true)const [newUser, setNewUser] = useState({ name: '', email: '', age: '' })// 獲取用戶列表const fetchUsers = async () => {try {const response = await fetch('/api/users')const result = await response.json()if (result.success) {setUsers(result.data)}} catch (error) {console.error('Error fetching users:', error)} finally {setLoading(false)}}// 創建用戶const createUser = async (e) => {e.preventDefault()try {const response = await fetch('/api/users/create', {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify(newUser)})const result = await response.json()if (result.success) {setUsers([...users, result.data])setNewUser({ name: '', email: '', age: '' })}} catch (error) {console.error('Error creating user:', error)}}// 刪除用戶const deleteUser = async (id) => {if (!confirm('確定要刪除這個用戶嗎？')) returntry {const response = await fetch(`/api/users/${id}`, {method: 'DELETE'})const result = await response.json()if (result.success) {setUsers(users.filter(user => user._id !== id))}} catch (error) {console.error('Error deleting user:', error)}}useEffect(() => {fetchUsers()}, [])if (loading) return <div>Loading...</div>return (<div><h2>User Management</h2>{/* 創建用戶表單 */}<form onSubmit={createUser}><inputtype="text"placeholder="Name"value={newUser.name}onChange={(e) => setNewUser({...newUser, name: e.target.value})}required/><inputtype="email"placeholder="Email"value={newUser.email}onChange={(e) => setNewUser({...newUser, email: e.target.value})}required/><inputtype="number"placeholder="Age"value={newUser.age}onChange={(e) => setNewUser({...newUser, age: parseInt(e.target.value)})}required/><button type="submit">Create User</button></form>{/* 用戶列表 */}<div>{users.map(user => (<div key={user._id} style={{ border: '1px solid #ccc', margin: '10px', padding: '10px' }}><h3>{user.name}</h3><p>Email: {user.email}</p><p>Age: {user.age}</p><button onClick={() => deleteUser(user._id)}>Delete</button></div>))}</div></div>)
}

10. 錯誤處理和最佳實踐

統一錯誤處理

創建 lib/errorHandler.js：

export function handleApiError(error, res) {console.error('API Error:', error)if (error.name === 'MongoServerError') {if (error.code === 11000) {// 重復鍵錯誤return res.status(400).json({success: false,error: 'Duplicate key error',details: error.keyValue})}}if (error.name === 'CastError') {// ObjectId 格式錯誤return res.status(400).json({success: false,error: 'Invalid ID format'})}// 通用錯誤return res.status(500).json({success: false,error: 'Internal server error'})
}

數據驗證

創建 lib/validation.js：

export function validateUser(userData) {const errors = []if (!userData.name || userData.name.trim().length < 2) {errors.push('Name must be at least 2 characters long')}if (!userData.email || !isValidEmail(userData.email)) {errors.push('Valid email is required')}if (!userData.age || userData.age < 0 || userData.age > 150) {errors.push('Age must be between 0 and 150')}return {isValid: errors.length === 0,errors}
}function isValidEmail(email) {const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/return emailRegex.test(email)
}

這個完整指南涵蓋了 Next.js 中使用 MongoDB 的所有基本操作，包括：