简介这是一套基于 Node.js、Express 与 MongoDB 构建的博客管理系统完整项目前端采用 Vue整体定位明确适合作为计算机相关专业的毕业设计、课程设计也适合想快速掌握前后端分离开发的初中级开发者参考学习。压缩包内共 675 个文件大小约 121.62MBJS 源码与 JSON 配置构成核心逻辑Markdown 说明文档与 SQL 脚本辅助部署和数据库初始化GIF 预览图与 PSD 设计稿便于查看界面效果与视觉资源。目前已有 163 人学习下载项目经过测试可快速部署运行资源内含工程化配置、依赖清单、字体图标、数据库脚本等目录结构清晰可直接导入开发环境使用。包内还包含设计源文件和说明文档既能支撑毕业设计答辩演示也能作为二次开发脚手架从前端页面到后端接口与数据库操作可完整理解博客系统的前后端协作方式与常见功能实现。1. 为什么 Node.js Express MongoDB 至今仍是做博客系统的最短路径如果你搜过这个标题多半是想找一个能直接跑起来的全栈项目当作毕业设计、个人作品集或者技术练手。Node.js、Express、MongoDB 这三件套在 2025 年被反复讨论“过时了没有”但现实是它依然是个人开发者从零做一个内容管理系统时投入产出比最高的组合。原因不复杂——JavaScript 全栈不需要维护两套语言心智Express 的中间件模型让路由、鉴权、日志、错误处理都能线性叠加MongoDB 的文档结构又在“文章 标签 评论”这种天然嵌套的数据形态面前比关系型数据库少绕很多弯。这篇笔记我会按自己真实做这类项目的顺序把从环境搭建到文章 CRUD、再到 JWT 登录鉴权和避坑细节全部过一遍。读者无论是刚装完 Node.js 的新手还是被 MongoDB 安装失败搞到想砸电脑的熟手都能在这篇里找到对应的一步。2. 先把三件套跑起来Node.js 环境、npm 镜像与 MongoDB 服务2.1 Node.js 安装与版本选择别用最新的用 LTS很多人第一步就翻车是因为去官网下载了带有 Current 字样的最新版。Node.js 的 Current 版本会频繁引入 V8 引擎和 API 层面的变化而 Express 5.x、Mongoose 8.x 这类库对 Node 版本有明确要求。我一般建议装 LTS 版本当前主流的 LTS 是 20.x 或 22.x选 20.x 更稳因为大部分第三方原生模块的预编译二进制都优先覆盖它。node -v npm -v如果这两条命令能正常输出版本号说明安装成功。但这里有个 Windows 用户几乎必踩的坑如果执行npm -v时报出npm : 无法加载文件 ...\npm.ps1因为在此系统上禁止运行脚本原因不是 npm 坏了而是 PowerShell 的执行策略默认禁用了.ps1脚本。这种报错的热搜量极大解决方法是管理员身份打开 PowerShell 执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned参数说明RemoteSigned表示本地脚本可以运行从互联网下载的脚本必须带有可信签名。对于开发机来说这是最推荐的策略不建议直接用Unrestricted否则以后运行任何来历不明的.ps1文件都不再有风险提示。改完策略后重新打开终端npm -v就能正常输出了。2.2 npm 镜像配置不配镜像等于浪费时间Node.js 装好只是第一步真正卡住新手的是npm install时的网络问题。国内网络环境下直接拉取官方 npm 源一个express包可能要等几分钟甚至直接超时更别说后面要装的mongoose、jsonwebtoken这种依赖树很深的包。我的做法是配置淘宝镜像作为 registry并且单独设置 Electron 镜像虽然本项目不用 Electron但这个习惯能帮你在做其他项目时少踩坑。npm config set registry https://registry.npmmirror.com npm config get registryset registry是把 npm 的包下载源指向国内镜像get registry用于验证配置是否生效。配完之后npm install的速度通常能从几分钟降到十几秒。注意一点镜像源有时会比官方源滞后几个小时如果你恰好需要安装一个当天刚发布的补丁版本遇到404错误时可以临时用npm install 包名 --registryhttps://registry.npmjs.org回退官方源不需要改全局配置。这里顺带提一下 nvm。不要在一台机器上只装一个 Node.js 版本用nvm-windows管理多版本是更职业的做法因为你可能这周做 Express 项目、下周做 Vite 项目每个项目要求的 Node 版本不一样。nvm 的常用命令就三个nvm install 20.17.0 nvm use 20.17.0 nvm ls逻辑说明nvm install下载指定版本的 Node.js 并自动配置环境变量nvm use切换当前终端会话使用的版本nvm ls查看本机已安装的所有版本。环境变量配置出错时在 Windows 的“系统属性 - 环境变量”里检查NVM_HOME和NVM_SYMLINK的路径是否分别指向 nvm 安装目录和当前版本软链目录这是 nvm 最常见的故障点。2.3 MongoDB 安装与服务启动装机玄学集中在三个环节MongoDB 的安装失败率在全部数据库里能排前三。常见的报错集中在三个环节安装包下载太慢、服务启动失败、Compass 连不上。先说我在 Windows 和 Linux 上各自验证过的方案。Windows 下推荐下载.msi安装包安装过程中注意两个选项一是要勾选Install MongoDB Compass图形化管理工具后面查看数据全靠它二是在 Service Configuration 页面建议取消Install MongoDB as a Service也就是不把 MongoDB 安装为 Windows 服务因为它默认装在C:\Program Files\MongoDB这个带空格的路径下后续脚本处理路径时容易出幺蛾子。手动启动更可控命令如下mongod --dbpath D:\mongodb-data --port 27017--dbpath指定数据存储目录必须提前手动创建好MongoDB 不会自动创建不存在的目录。--port指定监听端口默认就是 27017如果不冲突可以不写。执行后终端会打印一行Waiting for connections此时 MongoDB 就活了。不要关闭这个终端窗口关掉等于宕机。Linux 上的玩法不同我习惯用wget装二进制包而不是apt因为 Ubuntu 官方源的 MongoDB 版本通常偏旧。这里给出一个典型的安装命令序列wget https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-ubuntu2204-7.0.14.tgz tar -zxvf mongodb-linux-x86_64-ubuntu2204-7.0.14.tgz sudo mv mongodb-linux-x86_64-ubuntu2204-7.0.14 /usr/local/mongodb export PATH/usr/local/mongodb/bin:$PATH参数说明tar -zxvf中的 z 表示通过 gzip 解压x 表示解包v 是显示过程f 指定文件名。export PATH只在当前终端生效要永久生效需要把这一行写入~/.bashrc。之后启动方式与 Windows 一样用mongod --dbpath /data/mongo --fork --logpath /var/log/mongod.log其中--fork表示后台运行此时必须同时指定--logpath否则守护进程没有输出位置会报错。启动后验证连通性可以用 MongoDB 自带的客户端mongosh --host 127.0.0.1 --port 27017能进入test提示符说明连接成功。如果mongosh提示找不到命令检查 MongoDB 的bin目录是否在 PATH 中Windows 用户还需要注意.msi安装包默认不会配置环境变量需要在系统 PATH 里手动加上C:\Program Files\MongoDB\Server\7.0\bin这一条。Compass 连接时输入mongodb://127.0.0.1:27017就能看到可视化界面。如果连接报错先排查mongod窗口是否还开着再排查端口是否被占用——netstat -ano | findstr 27017看一下监听状态。3. 初始化 Express 项目与目录结构做博客管理系统的最小骨架3.1 用express-generator还是手写我选半自动初始化 Express 项目有两条路径一是用官方脚手架express-generator一条命令生成整个目录二是从零手写package.json和入口文件。脚手架的好处是目录规范、不用记中间件的挂载顺序坏处是它生成的是 Pug 模板引擎而做前后端分离的博客管理系统时我们几乎必定要提供 JSON API 而不是服务端渲染页面。我一般选用脚手架生成基础结构然后手动删除模板相关代码并改成 API 模式省去手写目录结构的时间。npx express-generator --no-view blog-server cd blog-server npm install--no-view参数很关键它让生成器不安装任何模板引擎生成的项目直接就是纯 API 骨架。npx会临时拉取express-generator包并执行执行完不污染全局环境。生成的目录里有bin/www、app.js、routes/这几个核心文件但我们还需要手动添加models/和middlewares/目录前者放 Mongoose 数据模型后者放鉴权中间件和错误处理中间件。生成后打开app.js默认代码里挂着express.json()和express.urlencoded()这两个内置中间件前者负责解析 JSON 请求体后者负责解析表单请求体做博客系统这两个都要保留。需要手动加的一行是跨域处理因为前端如果跑在 5173 端口Vite 默认后端跑在 3000 端口跨域请求会被浏览器拦截。// app.js const cors require(cors); app.use(cors());逻辑说明cors包本质是往响应头里添加Access-Control-Allow-Origin等字段。开发阶段直接app.use(cors())意味着允许所有来源访问生产环境必须要替换成白名单配置app.use(cors({ origin: [https://你的前端域名] }))否则任何人都能跨域调你的接口。3.2 Mongoose 连接 MongoDB连接字符串里的坑比想象中多装好 MongoDB 服务之后接下来要做的就是用 Mongoose 在 Node.js 进程里建立连接。mongoose是当前最主流的 MongoDB ODM 库它在官方驱动之上做了 Schema 定义和中间件支持让文档结构像 SQL 表一样有约束。安装命令npm install mongoose然后在项目根目录新建db.js写入连接逻辑。这里有个细节连接字符串里如果数据库名带特殊字符比如blog_2024没问题但如果你用了带空格的数据库名URL 编码会让你怀疑人生。我建议数据库名一律用小写字母和下划线组合。// db.js const mongoose require(mongoose); const connectDB async () { try { await mongoose.connect(mongodb://127.0.0.1:27017/blog_management, { serverSelectionTimeoutMS: 5000, }); console.log(MongoDB connected); } catch (err) { console.error(MongoDB connection error:, err.message); process.exit(1); } }; module.exports connectDB;参数说明serverSelectionTimeoutMS: 5000表示如果 5 秒内没有选择到可用的 MongoDB 服务器就报超时错误。这个参数在 MongoDB 服务没启动时能让你快速看到失败原因而不是傻等默认的 30 秒。connect方法的第一个参数里的blog_management就是数据库名如果这个库不存在MongoDB 会在第一次写入数据时自动创建不需要手动建库这对刚接触 MongoDB 的人来说可能有点反直觉——没有库插入第一条数据时库就出现了。然后在app.js顶部引入并调用// app.js const connectDB require(./db); connectDB();3.3 目录结构按业务模块拆不是按文件类型拆很多教程把routes下的文件按类型拆成article.js、user.js、comment.js这对小项目够用但项目一旦加上管理员后台、草稿箱、标签管理、文章归档这些功能单一文件会膨胀到几百行。我习惯按业务模块拆目录blog-server/ ├── app.js ├── db.js ├── bin/www ├── models/ │ ├── Article.js │ ├── User.js │ └── Comment.js ├── routes/ │ ├── article.js │ ├── user.js │ └── comment.js ├── middlewares/ │ ├── auth.js │ └── errorHandler.js └── package.jsonbin/www是 Express 生成的启动脚本内部读取环境变量PORT并启动 HTTP 服务器。启动命令是npm start它会执行node ./bin/www。如果开发阶段想让代码改动自动重启安装nodemon并把package.json的 scripts 改成scripts: { dev: nodemon ./bin/www, start: node ./bin/www }4. 设计博客数据模型文章、用户、评论的 Schema 边界4.1 文章模型正文存储与富文本的取舍博客系统的核心是文章文章的字段看似简单但“正文用什么格式存”“标签存数组还是存字符串”“摘要要不要单独冗余”这三个问题会直接影响后续功能扩展。我给的方案是基于大部分人做过的真实项目经验标签用字符串数组摘要单独存一份。// models/Article.js const mongoose require(mongoose); const articleSchema new mongoose.Schema( { title: { type: String, required: true, trim: true }, content: { type: String, required: true }, summary: { type: String, required: true }, tags: [{ type: String, trim: true, lowercase: true }], category: { type: String, default: 未分类 }, cover: { type: String, default: }, status: { type: String, enum: [draft, published], default: published }, viewCount: { type: Number, default: 0 }, author: { type: mongoose.Schema.Types.ObjectId, ref: User, required: true }, }, { timestamps: true } ); module.exports mongoose.model(Article, articleSchema);参数说明trim: true会在保存时自动去掉字符串首尾空格避免出现前端, 后端这种带空格的脏标签。lowercase: true把标签统一转小写这样通过标签筛选文章时不会出现NodeJs和nodejs被当成两个标签的情况。enum数组限定status字段只能取draft和published两个值从模型层面挡住非法状态。timestamps: true自动生成createdAt和updatedAt两个时间戳字段不需要手动维护。ref: User建立文章和用户的外键关联后续用populate(author)查文章时可以直接带出作者用户名和头像。正文存储是另一个值得说清楚的决策点。多数博客系统的正文有三种存法纯文本、HTML 字符串、Markdown 源文本加渲染结果双存。最省事的是存 HTML——前端拿到什么就渲染什么但 XSS 风险高用户一旦能提交富文本攻击者就能在文章里嵌入script标签。我的建议是存 Markdown前端用marked或markdown-it渲染成 HTML渲染前经过消毒库dompurify过滤脚本标签。4.2 用户模型密码哈希与角色字段的边界用户模型里最容易被忽略的是“角色”字段很多教程只存用户名和密码结果后面要做管理员后台时又要给数据库手动加字段。不如从一开始就内置角色。// models/User.js const mongoose require(mongoose); const bcrypt require(bcryptjs); const userSchema new mongoose.Schema( { username: { type: String, required: true, unique: true }, email: { type: String, required: true, unique: true, lowercase: true }, passwordHash: { type: String, required: true }, role: { type: String, enum: [admin, author], default: author }, avatar: { type: String, default: }, }, { timestamps: true } ); userSchema.methods.setPassword function (plainPassword) { const salt bcrypt.genSaltSync(10); this.passwordHash bcrypt.hashSync(plainPassword, salt); }; userSchema.methods.validatePassword function (plainPassword) { return bcrypt.compareSync(plainPassword, this.passwordHash); }; module.exports mongoose.model(User, userSchema);逻辑说明bcrypt.genSaltSync(10)生成一个包含 10 轮加盐处理的盐值bcrypt.hashSync用这个盐值对明文密码做不可逆哈希。注意模型里从来没有保存过明文密码数据库被拖库也不怕。这里补充一个值得讨论的点密码字段命名为passwordHash而不是password是为了避免某个菜鸟同事在代码里直接user.password 123456绕过加密逻辑——看到 Hash 后缀你至少会意识到这里该用setPassword方法。用户注册接口里只需要调用setPassword再保存即可。不要自己实现 MD5 加盐——bcryptjs是专业方案故意设计成计算耗时在 100ms 级别来抵御暴力破解这是前端防不住、后端必须做的事。4.3 评论模型与关联查询评论模型是典型的子文档结构可以直接嵌套在文章文档里也可以独立成集合。小项目我会选择独立集合因为评论的增删频率比文章高独立集合不会让文章文档越来越臃肿而且做“最新评论”列表时只需要查评论表而不需要遍历所有文章。// models/Comment.js const mongoose require(mongoose); const commentSchema new mongoose.Schema( { article: { type: mongoose.Schema.Types.ObjectId, ref: Article, required: true }, user: { type: mongoose.Schema.Types.ObjectId, ref: User, required: true }, content: { type: String, required: true, maxlength: 1000 }, }, { timestamps: true } ); module.exports mongoose.model(Comment, commentSchema);查询某个文章下的所有评论时关联查询是必经之路const comments await Comment.find({ article: articleId }) .populate(user, username avatar) .sort({ createdAt: -1 });populate的第二个参数是字段白名单只取username和avatar避免查询结果里夹带passwordHash。万一哪天接口被拖出去打美化的评论列表这一步能降低泄露敏感字段的风险。5. 实现 RESTful API 与 JWT 登录鉴权从路由到中间件的完整链路5.1 文章接口列表、详情、创建、更新、删除的标准写法接口设计遵循 RESTful 原则文章资源的五个核心接口分别是GET /api/articles、GET /api/articles/:id、POST /api/articles、PUT /api/articles/:id、DELETE /api/articles/:id。列表接口一定要加分页不然文章多了之后单次响应体积会失控。// routes/article.js const express require(express); const router express.Router(); const Article require(../models/Article); // 公开接口分页获取已发布文章 router.get(/api/articles, async (req, res, next) { try { const page parseInt(req.query.page) || 1; const pageSize parseInt(req.query.pageSize) || 10; const skip (page - 1) * pageSize; const query { status: published }; const [articles, total] await Promise.all([ Article.find(query).populate(author, username).sort({ createdAt: -1 }).skip(skip).limit(pageSize), Article.countDocuments(query), ]); res.json({ data: articles, page, pageSize, total }); } catch (err) { next(err); } }); module.exports router;逻辑说明parseInt(req.query.page) || 1处理两种边界情况——page没传时默认第一页page传了但解析失败比如收到abc时也回退到第一页。Promise.all并行执行文章列表查询和总数查询避免串行等待浪费时间。skip计算跳过的文档数limit限制返回条数。分页接口的返回值附带total字段前端渲染分页器时需要用总数除以每页条数得出总页数。创建文章的接口需要走鉴权中间件。先演示中间件怎么写再挂到路由上// middlewares/auth.js const jwt require(jsonwebtoken); const User require(../models/User); const authMiddleware async (req, res, next) { try { const token req.headers.authorization?.replace(Bearer , ); if (!token) { return res.status(401).json({ message: 未登录或登录已过期 }); } const decoded jwt.verify(token, process.env.JWT_SECRET); const user await User.findById(decoded.userId); if (!user) { return res.status(401).json({ message: 用户不存在 }); } req.user user; next(); } catch (err) { return res.status(401).json({ message: 无效的令牌 }); } }; module.exports authMiddleware;参数说明请求头里的 Authorization 格式是Bearer token因此先用replace(Bearer , )去掉前缀取出纯 token。jwt.verify在校验篡改和过期时会抛异常直接走401。findById从数据库查用户并挂到req.user上后续代码可以直接用req.user._id识别当前登录者是哪个用户。process.env.JWT_SECRET是环境变量生产环境必须设置并且足够随机开发环境可以在package.json的同级目录创建.env文件用dotenv加载。挂载到创建文章的接口上router.post(/api/articles, authMiddleware, async (req, res, next) { try { const article new Article({ ...req.body, author: req.user._id, }); await article.save(); res.status(201).json(article); } catch (err) { next(err); } });authMiddleware在这里的作用是保证只有登录用户才能发布文章。如果只想让管理员发文章可以在authMiddleware之后再加一个adminOnly中间件检查req.user.role admin。5.2 用户注册与登录JWT 签发逻辑注册接口其实只有一步创建用户并设置密码router.post(/api/auth/register, async (req, res, next) { try { const { username, email, password, role } req.body; const user new User({ username, email, role: role || author }); user.setPassword(password); await user.save(); res.status(201).json({ message: 注册成功 }); } catch (err) { next(err); } });登录接口负责校验密码并签发 JWTrouter.post(/api/auth/login, async (req, res, next) { try { const { username, password } req.body; const user await User.findOne({ username }); if (!user || !user.validatePassword(password)) { return res.status(401).json({ message: 用户名或密码错误 }); } const token jwt.sign({ userId: user._id, role: user.role }, process.env.JWT_SECRET, { expiresIn: 7d, }); res.json({ token, user: { id: user._id, username: user.username, role: user.role }, }); } catch (err) { next(err); } });expiresIn: 7d表示令牌有效期 7 天超过 7 天后前端需要引导用户重新登录。JWT 被设计成无状态服务端不保存 session所以“强制退出登录”在纯 JWT 方案里是做不到的——除非引入黑名单机制但那已经超出博客系统范畴了。对于这个项目7 天过期是可以接受的代价是如果用户密码泄露令牌最长还有 7 天有效。真要更安全口头建议是缩短到 1 天加 refresh token 机制但不要为了一个博客管理系统把复杂度拉满。5.3 文件上传与图片处理中间件选型封面图片是博客系统的刚需我用multer做文件上传这是 Express 生态里最成熟的方案它把上传文件从req.files里暴露出来配合sharp做图片压缩可以控制封面图体积。安装两个包npm install multer sharp上传接口的典型写法// routes/upload.js const multer require(multer); const sharp require(sharp); const path require(path); const storage multer.diskStorage({ destination: (req, file, cb) cb(null, public/uploads), filename: (req, file, cb) { const unique Date.now() - Math.round(Math.random() * 1e9); cb(null, unique path.extname(file.originalname)); }, }); const upload multer({ storage, limits: { fileSize: 5 * 1024 * 1024 }, fileFilter: (req, file, cb) { const allowed [image/jpeg, image/png, image/webp]; if (!allowed.includes(file.mimetype)) { return cb(new Error(仅支持 JPEG、PNG、WebP 格式)); } cb(null, true); }, }); router.post(/api/upload/cover, authMiddleware, upload.single(cover), async (req, res, next) { try { const filePath req.file.path; const outputPath filePath.replace(path.extname(filePath), .webp); await sharp(filePath).resize(1200, 630).webp({ quality: 80 }).toFile(outputPath); res.json({ url: /uploads/ path.basename(outputPath) }); } catch (err) { next(err); } });参数说明fileSize: 5 * 1024 * 1024限制单张图片不能超过 5MB超出后 multer 会返回错误。fileFilter从 MIME 类型层面拦截非图片文件。文件名用时间戳加随机数拼接避免中文文件名和空格造成 URL 编码问题。sharp把上传的图片压缩成 1200x630 的 WebP体积通常能减少 60% 以上。存储路径不建议放在项目根目录下的uploads里最好放public/uploads并通过app.use(express.static(public))暴露出去否则客户端无法通过 URL 访问图片。5.4 错误处理中间件最后一个 app.useExpress 的错误处理中间件长着四个参数这有个业内调侃的说法叫作“不看参数数量就挂不上”因为express是靠参数个数识别错误处理中间件的。它必须挂在所有路由之后// middlewares/errorHandler.js const errorHandler (err, req, res, next) { const statusCode err.status || 500; res.status(statusCode).json({ message: err.message || 服务器内部错误, stack: process.env.NODE_ENV production ? undefined : err.stack, }); }; module.exports errorHandler;然后在app.js里最后一行挂载const errorHandler require(./middlewares/errorHandler); app.use(errorHandler);逻辑说明开发环境下stack字段能打印完整错误调用栈生产环境置为undefined避免泄露网络路径和模块结构。这个中间件统一收口所有路由里next(err)传出的异常如果你不在最后挂它任何一处数据库操作抛错都会导致进程崩溃并返回一张 HTML 错误页。6. 避坑与常见问题排查安装、运行、数据三层视角的踩坑记录6.1 安装层npm 与 MongoDB 的高频翻车现场现象执行npm install报npm ERR! code ERESOLVE依赖树解析失败。原因这是 npm 7 之后对 peerDependencies 的严格校验导致的常见于某些包版本之间不兼容。比如全局安装了某个版本的 Express项目里又装了一个不兼容的版本npm 就会罢工。解决先尝试npm install --legacy-peer-deps让 npm 跳过 peerDependency 冲突检查。如果还不行删除node_modules和package-lock.json后重新安装。我在实际项目中遇到过mongoose与mongodb-driver版本不匹配导致的连接失败这类问题直接看项目 package.json 里锁定的版本号再去 npm 官网比对两个包的 peerDependencies 范围。现象本地能连 MongoDB但代码里mongoose.connect一直超时报Server selection timed out。原因数据库服务没启动或者连接字符串里的主机名写成了localhost而 MongoDB 绑定的是 IPv6 地址。解决开发环境统一用127.0.0.1而不是localhost因为有些操作系统会把localhost解析成::1MongoDB 默认监听的是0.0.0.0两者在某些网络栈下会错开。再验证服务是否真的在跑mongosh --eval db.runCommand({ ping: 1 })能返回ok: 1说明数据库层面没问题。6.2 运行层Express 中间件顺序就是命根子现象请求打到接口返回 404但路由文件里明明写了这个路径。原因路由文件挂载顺序错误。如果app.use(/api, articleRouter)写在app.use(express.json())之前请求体还没被解析POST 接口拿到的是undefined。另一个经典错误是把错误处理中间件挂在了路由之前导致next(err)进了错误处理但路由还没匹配完。解决中间件挂载顺序从上到下依次是express.json()→cors()→ 静态文件目录 → 路由 → 404 兜底 → 错误处理中间件。这个顺序不要打乱否则就会出现“接口明明存在但请求不达路由”的诡异现象。6.3 数据层MongoDB 查询聚合与删除操作的血泪经验现象用Article.deleteOne({ _id: id })删文章成功了但评论列表里还有对应文章的历史评论前端渲染详情页时一加载就报空指针。原因MongoDB 没有外键级联删除这是它与 SQL 数据库最大的心智差异。删除文章不会自动删评论。解决删除文章的接口里手动补一条删除评论的语句const articleId req.params.id; await Article.deleteOne({ _id: articleId }); await Comment.deleteMany({ article: articleId });现象db.articles.find({ tags: Nodejs })查不出刚创建的标签为nodejs的文章因为Schema 里lowercase: true把标签转换成了小写但查询条件里写的是首字母大写。原因查询时不会自动调用 Schema 的lowercase转换它只作用于写入阶段。解决查询前手动tags.toLowerCase()或者干脆统一用$regex: new RegExp(^ tag $, i)做不区分大小写的精确匹配。正则的i标志表示忽略大小写这是处理用户输入查询条件时的默认做法。现象Article.findById(id)返回 null但用 Compass 看数据明明存在。原因前端传来的id不是合法的 ObjectId 字符串可能是 undefined带了个空格或者是被截断的 23 位短字符串。Mongoose 对格式不合法的 id 会直接返回 null 而不是抛异常导致你排查时一脸懵。解决先用 Mongoose 内置的类型校验mongoose.Types.ObjectId.isValid(id)返回 false 时直接返回 400 错误不要让非法 id 进到数据库查询层。6.4 前后端联调跨域与请求体格式的两个细节现象前端用 axios 发起 POST 请求后端收到了但req.body是空对象。原因前端没设置Content-Type: application/jsonaxios 默认对普通对象用的是application/x-www-form-urlencoded而后端只用了express.json()解析 JSON 格式没有express.urlencoded()兜底。解决axios 请求时显式指定axios.post(/api/auth/login, data, { headers: { Content-Type: application/json }, });现象前端登录后存储了 token但刷新页面后接口全部 401。原因axios 拦截器里没把 token 塞到请求头或者把 token 存在了sessionStorage里刷新标签页后 sessionStorage 还在但浏览器在新标签页打开时 session 不共享。解决用localStorage存 token并在 axios 拦截器里统一加头axios.interceptors.request.use(config { const token localStorage.getItem(token); if (token) { config.headers.Authorization Bearer ${token}; } return config; });7. 部署验证与压测用curl和k6给博客系统做一次体检整套代码写完后部署和验证是很多人最心虚的环节。代码在本地跑得飞起一上服务器就 502核心原因是环境变量缺失、端口冲突、数据库没有守护进程这三个问题。部署我不展开讲 Nginx 配置只讲做完部署后必须执行的验证步骤——这比教程里铺天盖地的配置片段更值钱。先验证健康检查接口。确保你的app.js里有这样一条路由router.get(/api/health, (req, res) res.json({ status: ok, time: Date.now() }));部署完成后运行curl http://你的服务器IP:3000/api/health期望返回{status:ok}且time字段是最近几秒内的毫秒时间戳。这一步能同时验证进程活着、端口互通、Nginx 反向代理没配错。接下来验证鉴权链路用一段完整的curl命令模拟登录并获取 tokencurl -X POST http://你的服务器IP:3000/api/auth/login \ -H Content-Type: application/json \ -d {username: admin, password: admin123} \ -c cookies.txt返回结果里应该包含token字段把它复制到下面的命令里curl -X POST http://你的服务器IP:3000/api/articles \ -H Content-Type: application/json \ -H Authorization: Bearer 替换成上面的token \ -d {title: 部署验证文章, content: 测试内容, summary: 测试摘要}返回 201 和文章对象说明数据库写入正常、鉴权中间件没有误伤合法请求。接着用GET拉取列表接口验证分页参数curl http://你的服务器IP:3000/api/articles?page1pageSize5验证total字段和你刚写入的文章数量一致——这里特别提醒分页参数经常因为手滑写成了pageSize0Mongoose 的.limit(0)会返回空数组而不是报错很多人排查半天以为接口坏了其实是参数传错了。我在本地测试里加了一条规则前端传入的pageSize一律用Math.min(100, Math.max(1, n))夹在 1 到 100 之间。压测部分如果你用的是k6一个开源压测工具最小脚本长这样// load-test.js import http from k6/http; import { check } from k6; export const options { vus: 20, duration: 30s, }; export default function () { const res http.get(http://127.0.0.1:3000/api/articles?page1pageSize10); check(res, { status is 200: (r) r.status 200, response time 500ms: (r) r.timings.duration 500, }); }k6 run load-test.jsvus: 20表示 20 个虚拟用户并发duration: 30s持续压 30 秒。压测前先把 MongoDB 服务端和 Node 进程的日志都开着如果接口延迟普遍超过 500ms大概率是缺少索引导致的集合扫描。对博客系统最有价值的索引是文章表的{ status: 1, createdAt: -1 }复合索引MySQL 里的查询优化经验在 MongoDB 里同样适用。压测和验证做完我最后提一个自己吃过亏的习惯上线前务必在app.js里打印启动日志至少包含监听端口和数据库状态。很多生产事故不是代码写错而是换了一台服务器后数据库地址忘了改、环境变量没带过去却毫无感知。日志是玄学排查后唯一的后悔药别省。希望这篇从环境搭建到接口验证的完整记录能帮你在做博客管理系统时少走几步弯路。踩坑不可怕可怕的是同一个坑踩完还不留日志下次换台机器接着踩——把这篇里的验证命令当成固定动作你会在后续的全栈项目里省很多时间。本文还有配套的精品资源点击获取
Node.js + Express + MongoDB 搭建博客全栈项目实战
简介这是一套基于 Node.js、Express 与 MongoDB 构建的博客管理系统完整项目前端采用 Vue整体定位明确适合作为计算机相关专业的毕业设计、课程设计也适合想快速掌握前后端分离开发的初中级开发者参考学习。压缩包内共 675 个文件大小约 121.62MBJS 源码与 JSON 配置构成核心逻辑Markdown 说明文档与 SQL 脚本辅助部署和数据库初始化GIF 预览图与 PSD 设计稿便于查看界面效果与视觉资源。目前已有 163 人学习下载项目经过测试可快速部署运行资源内含工程化配置、依赖清单、字体图标、数据库脚本等目录结构清晰可直接导入开发环境使用。包内还包含设计源文件和说明文档既能支撑毕业设计答辩演示也能作为二次开发脚手架从前端页面到后端接口与数据库操作可完整理解博客系统的前后端协作方式与常见功能实现。1. 为什么 Node.js Express MongoDB 至今仍是做博客系统的最短路径如果你搜过这个标题多半是想找一个能直接跑起来的全栈项目当作毕业设计、个人作品集或者技术练手。Node.js、Express、MongoDB 这三件套在 2025 年被反复讨论“过时了没有”但现实是它依然是个人开发者从零做一个内容管理系统时投入产出比最高的组合。原因不复杂——JavaScript 全栈不需要维护两套语言心智Express 的中间件模型让路由、鉴权、日志、错误处理都能线性叠加MongoDB 的文档结构又在“文章 标签 评论”这种天然嵌套的数据形态面前比关系型数据库少绕很多弯。这篇笔记我会按自己真实做这类项目的顺序把从环境搭建到文章 CRUD、再到 JWT 登录鉴权和避坑细节全部过一遍。读者无论是刚装完 Node.js 的新手还是被 MongoDB 安装失败搞到想砸电脑的熟手都能在这篇里找到对应的一步。2. 先把三件套跑起来Node.js 环境、npm 镜像与 MongoDB 服务2.1 Node.js 安装与版本选择别用最新的用 LTS很多人第一步就翻车是因为去官网下载了带有 Current 字样的最新版。Node.js 的 Current 版本会频繁引入 V8 引擎和 API 层面的变化而 Express 5.x、Mongoose 8.x 这类库对 Node 版本有明确要求。我一般建议装 LTS 版本当前主流的 LTS 是 20.x 或 22.x选 20.x 更稳因为大部分第三方原生模块的预编译二进制都优先覆盖它。node -v npm -v如果这两条命令能正常输出版本号说明安装成功。但这里有个 Windows 用户几乎必踩的坑如果执行npm -v时报出npm : 无法加载文件 ...\npm.ps1因为在此系统上禁止运行脚本原因不是 npm 坏了而是 PowerShell 的执行策略默认禁用了.ps1脚本。这种报错的热搜量极大解决方法是管理员身份打开 PowerShell 执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned参数说明RemoteSigned表示本地脚本可以运行从互联网下载的脚本必须带有可信签名。对于开发机来说这是最推荐的策略不建议直接用Unrestricted否则以后运行任何来历不明的.ps1文件都不再有风险提示。改完策略后重新打开终端npm -v就能正常输出了。2.2 npm 镜像配置不配镜像等于浪费时间Node.js 装好只是第一步真正卡住新手的是npm install时的网络问题。国内网络环境下直接拉取官方 npm 源一个express包可能要等几分钟甚至直接超时更别说后面要装的mongoose、jsonwebtoken这种依赖树很深的包。我的做法是配置淘宝镜像作为 registry并且单独设置 Electron 镜像虽然本项目不用 Electron但这个习惯能帮你在做其他项目时少踩坑。npm config set registry https://registry.npmmirror.com npm config get registryset registry是把 npm 的包下载源指向国内镜像get registry用于验证配置是否生效。配完之后npm install的速度通常能从几分钟降到十几秒。注意一点镜像源有时会比官方源滞后几个小时如果你恰好需要安装一个当天刚发布的补丁版本遇到404错误时可以临时用npm install 包名 --registryhttps://registry.npmjs.org回退官方源不需要改全局配置。这里顺带提一下 nvm。不要在一台机器上只装一个 Node.js 版本用nvm-windows管理多版本是更职业的做法因为你可能这周做 Express 项目、下周做 Vite 项目每个项目要求的 Node 版本不一样。nvm 的常用命令就三个nvm install 20.17.0 nvm use 20.17.0 nvm ls逻辑说明nvm install下载指定版本的 Node.js 并自动配置环境变量nvm use切换当前终端会话使用的版本nvm ls查看本机已安装的所有版本。环境变量配置出错时在 Windows 的“系统属性 - 环境变量”里检查NVM_HOME和NVM_SYMLINK的路径是否分别指向 nvm 安装目录和当前版本软链目录这是 nvm 最常见的故障点。2.3 MongoDB 安装与服务启动装机玄学集中在三个环节MongoDB 的安装失败率在全部数据库里能排前三。常见的报错集中在三个环节安装包下载太慢、服务启动失败、Compass 连不上。先说我在 Windows 和 Linux 上各自验证过的方案。Windows 下推荐下载.msi安装包安装过程中注意两个选项一是要勾选Install MongoDB Compass图形化管理工具后面查看数据全靠它二是在 Service Configuration 页面建议取消Install MongoDB as a Service也就是不把 MongoDB 安装为 Windows 服务因为它默认装在C:\Program Files\MongoDB这个带空格的路径下后续脚本处理路径时容易出幺蛾子。手动启动更可控命令如下mongod --dbpath D:\mongodb-data --port 27017--dbpath指定数据存储目录必须提前手动创建好MongoDB 不会自动创建不存在的目录。--port指定监听端口默认就是 27017如果不冲突可以不写。执行后终端会打印一行Waiting for connections此时 MongoDB 就活了。不要关闭这个终端窗口关掉等于宕机。Linux 上的玩法不同我习惯用wget装二进制包而不是apt因为 Ubuntu 官方源的 MongoDB 版本通常偏旧。这里给出一个典型的安装命令序列wget https://fastdl.mongodb.org/linux/mongodb-linux-x86_64-ubuntu2204-7.0.14.tgz tar -zxvf mongodb-linux-x86_64-ubuntu2204-7.0.14.tgz sudo mv mongodb-linux-x86_64-ubuntu2204-7.0.14 /usr/local/mongodb export PATH/usr/local/mongodb/bin:$PATH参数说明tar -zxvf中的 z 表示通过 gzip 解压x 表示解包v 是显示过程f 指定文件名。export PATH只在当前终端生效要永久生效需要把这一行写入~/.bashrc。之后启动方式与 Windows 一样用mongod --dbpath /data/mongo --fork --logpath /var/log/mongod.log其中--fork表示后台运行此时必须同时指定--logpath否则守护进程没有输出位置会报错。启动后验证连通性可以用 MongoDB 自带的客户端mongosh --host 127.0.0.1 --port 27017能进入test提示符说明连接成功。如果mongosh提示找不到命令检查 MongoDB 的bin目录是否在 PATH 中Windows 用户还需要注意.msi安装包默认不会配置环境变量需要在系统 PATH 里手动加上C:\Program Files\MongoDB\Server\7.0\bin这一条。Compass 连接时输入mongodb://127.0.0.1:27017就能看到可视化界面。如果连接报错先排查mongod窗口是否还开着再排查端口是否被占用——netstat -ano | findstr 27017看一下监听状态。3. 初始化 Express 项目与目录结构做博客管理系统的最小骨架3.1 用express-generator还是手写我选半自动初始化 Express 项目有两条路径一是用官方脚手架express-generator一条命令生成整个目录二是从零手写package.json和入口文件。脚手架的好处是目录规范、不用记中间件的挂载顺序坏处是它生成的是 Pug 模板引擎而做前后端分离的博客管理系统时我们几乎必定要提供 JSON API 而不是服务端渲染页面。我一般选用脚手架生成基础结构然后手动删除模板相关代码并改成 API 模式省去手写目录结构的时间。npx express-generator --no-view blog-server cd blog-server npm install--no-view参数很关键它让生成器不安装任何模板引擎生成的项目直接就是纯 API 骨架。npx会临时拉取express-generator包并执行执行完不污染全局环境。生成的目录里有bin/www、app.js、routes/这几个核心文件但我们还需要手动添加models/和middlewares/目录前者放 Mongoose 数据模型后者放鉴权中间件和错误处理中间件。生成后打开app.js默认代码里挂着express.json()和express.urlencoded()这两个内置中间件前者负责解析 JSON 请求体后者负责解析表单请求体做博客系统这两个都要保留。需要手动加的一行是跨域处理因为前端如果跑在 5173 端口Vite 默认后端跑在 3000 端口跨域请求会被浏览器拦截。// app.js const cors require(cors); app.use(cors());逻辑说明cors包本质是往响应头里添加Access-Control-Allow-Origin等字段。开发阶段直接app.use(cors())意味着允许所有来源访问生产环境必须要替换成白名单配置app.use(cors({ origin: [https://你的前端域名] }))否则任何人都能跨域调你的接口。3.2 Mongoose 连接 MongoDB连接字符串里的坑比想象中多装好 MongoDB 服务之后接下来要做的就是用 Mongoose 在 Node.js 进程里建立连接。mongoose是当前最主流的 MongoDB ODM 库它在官方驱动之上做了 Schema 定义和中间件支持让文档结构像 SQL 表一样有约束。安装命令npm install mongoose然后在项目根目录新建db.js写入连接逻辑。这里有个细节连接字符串里如果数据库名带特殊字符比如blog_2024没问题但如果你用了带空格的数据库名URL 编码会让你怀疑人生。我建议数据库名一律用小写字母和下划线组合。// db.js const mongoose require(mongoose); const connectDB async () { try { await mongoose.connect(mongodb://127.0.0.1:27017/blog_management, { serverSelectionTimeoutMS: 5000, }); console.log(MongoDB connected); } catch (err) { console.error(MongoDB connection error:, err.message); process.exit(1); } }; module.exports connectDB;参数说明serverSelectionTimeoutMS: 5000表示如果 5 秒内没有选择到可用的 MongoDB 服务器就报超时错误。这个参数在 MongoDB 服务没启动时能让你快速看到失败原因而不是傻等默认的 30 秒。connect方法的第一个参数里的blog_management就是数据库名如果这个库不存在MongoDB 会在第一次写入数据时自动创建不需要手动建库这对刚接触 MongoDB 的人来说可能有点反直觉——没有库插入第一条数据时库就出现了。然后在app.js顶部引入并调用// app.js const connectDB require(./db); connectDB();3.3 目录结构按业务模块拆不是按文件类型拆很多教程把routes下的文件按类型拆成article.js、user.js、comment.js这对小项目够用但项目一旦加上管理员后台、草稿箱、标签管理、文章归档这些功能单一文件会膨胀到几百行。我习惯按业务模块拆目录blog-server/ ├── app.js ├── db.js ├── bin/www ├── models/ │ ├── Article.js │ ├── User.js │ └── Comment.js ├── routes/ │ ├── article.js │ ├── user.js │ └── comment.js ├── middlewares/ │ ├── auth.js │ └── errorHandler.js └── package.jsonbin/www是 Express 生成的启动脚本内部读取环境变量PORT并启动 HTTP 服务器。启动命令是npm start它会执行node ./bin/www。如果开发阶段想让代码改动自动重启安装nodemon并把package.json的 scripts 改成scripts: { dev: nodemon ./bin/www, start: node ./bin/www }4. 设计博客数据模型文章、用户、评论的 Schema 边界4.1 文章模型正文存储与富文本的取舍博客系统的核心是文章文章的字段看似简单但“正文用什么格式存”“标签存数组还是存字符串”“摘要要不要单独冗余”这三个问题会直接影响后续功能扩展。我给的方案是基于大部分人做过的真实项目经验标签用字符串数组摘要单独存一份。// models/Article.js const mongoose require(mongoose); const articleSchema new mongoose.Schema( { title: { type: String, required: true, trim: true }, content: { type: String, required: true }, summary: { type: String, required: true }, tags: [{ type: String, trim: true, lowercase: true }], category: { type: String, default: 未分类 }, cover: { type: String, default: }, status: { type: String, enum: [draft, published], default: published }, viewCount: { type: Number, default: 0 }, author: { type: mongoose.Schema.Types.ObjectId, ref: User, required: true }, }, { timestamps: true } ); module.exports mongoose.model(Article, articleSchema);参数说明trim: true会在保存时自动去掉字符串首尾空格避免出现前端, 后端这种带空格的脏标签。lowercase: true把标签统一转小写这样通过标签筛选文章时不会出现NodeJs和nodejs被当成两个标签的情况。enum数组限定status字段只能取draft和published两个值从模型层面挡住非法状态。timestamps: true自动生成createdAt和updatedAt两个时间戳字段不需要手动维护。ref: User建立文章和用户的外键关联后续用populate(author)查文章时可以直接带出作者用户名和头像。正文存储是另一个值得说清楚的决策点。多数博客系统的正文有三种存法纯文本、HTML 字符串、Markdown 源文本加渲染结果双存。最省事的是存 HTML——前端拿到什么就渲染什么但 XSS 风险高用户一旦能提交富文本攻击者就能在文章里嵌入script标签。我的建议是存 Markdown前端用marked或markdown-it渲染成 HTML渲染前经过消毒库dompurify过滤脚本标签。4.2 用户模型密码哈希与角色字段的边界用户模型里最容易被忽略的是“角色”字段很多教程只存用户名和密码结果后面要做管理员后台时又要给数据库手动加字段。不如从一开始就内置角色。// models/User.js const mongoose require(mongoose); const bcrypt require(bcryptjs); const userSchema new mongoose.Schema( { username: { type: String, required: true, unique: true }, email: { type: String, required: true, unique: true, lowercase: true }, passwordHash: { type: String, required: true }, role: { type: String, enum: [admin, author], default: author }, avatar: { type: String, default: }, }, { timestamps: true } ); userSchema.methods.setPassword function (plainPassword) { const salt bcrypt.genSaltSync(10); this.passwordHash bcrypt.hashSync(plainPassword, salt); }; userSchema.methods.validatePassword function (plainPassword) { return bcrypt.compareSync(plainPassword, this.passwordHash); }; module.exports mongoose.model(User, userSchema);逻辑说明bcrypt.genSaltSync(10)生成一个包含 10 轮加盐处理的盐值bcrypt.hashSync用这个盐值对明文密码做不可逆哈希。注意模型里从来没有保存过明文密码数据库被拖库也不怕。这里补充一个值得讨论的点密码字段命名为passwordHash而不是password是为了避免某个菜鸟同事在代码里直接user.password 123456绕过加密逻辑——看到 Hash 后缀你至少会意识到这里该用setPassword方法。用户注册接口里只需要调用setPassword再保存即可。不要自己实现 MD5 加盐——bcryptjs是专业方案故意设计成计算耗时在 100ms 级别来抵御暴力破解这是前端防不住、后端必须做的事。4.3 评论模型与关联查询评论模型是典型的子文档结构可以直接嵌套在文章文档里也可以独立成集合。小项目我会选择独立集合因为评论的增删频率比文章高独立集合不会让文章文档越来越臃肿而且做“最新评论”列表时只需要查评论表而不需要遍历所有文章。// models/Comment.js const mongoose require(mongoose); const commentSchema new mongoose.Schema( { article: { type: mongoose.Schema.Types.ObjectId, ref: Article, required: true }, user: { type: mongoose.Schema.Types.ObjectId, ref: User, required: true }, content: { type: String, required: true, maxlength: 1000 }, }, { timestamps: true } ); module.exports mongoose.model(Comment, commentSchema);查询某个文章下的所有评论时关联查询是必经之路const comments await Comment.find({ article: articleId }) .populate(user, username avatar) .sort({ createdAt: -1 });populate的第二个参数是字段白名单只取username和avatar避免查询结果里夹带passwordHash。万一哪天接口被拖出去打美化的评论列表这一步能降低泄露敏感字段的风险。5. 实现 RESTful API 与 JWT 登录鉴权从路由到中间件的完整链路5.1 文章接口列表、详情、创建、更新、删除的标准写法接口设计遵循 RESTful 原则文章资源的五个核心接口分别是GET /api/articles、GET /api/articles/:id、POST /api/articles、PUT /api/articles/:id、DELETE /api/articles/:id。列表接口一定要加分页不然文章多了之后单次响应体积会失控。// routes/article.js const express require(express); const router express.Router(); const Article require(../models/Article); // 公开接口分页获取已发布文章 router.get(/api/articles, async (req, res, next) { try { const page parseInt(req.query.page) || 1; const pageSize parseInt(req.query.pageSize) || 10; const skip (page - 1) * pageSize; const query { status: published }; const [articles, total] await Promise.all([ Article.find(query).populate(author, username).sort({ createdAt: -1 }).skip(skip).limit(pageSize), Article.countDocuments(query), ]); res.json({ data: articles, page, pageSize, total }); } catch (err) { next(err); } }); module.exports router;逻辑说明parseInt(req.query.page) || 1处理两种边界情况——page没传时默认第一页page传了但解析失败比如收到abc时也回退到第一页。Promise.all并行执行文章列表查询和总数查询避免串行等待浪费时间。skip计算跳过的文档数limit限制返回条数。分页接口的返回值附带total字段前端渲染分页器时需要用总数除以每页条数得出总页数。创建文章的接口需要走鉴权中间件。先演示中间件怎么写再挂到路由上// middlewares/auth.js const jwt require(jsonwebtoken); const User require(../models/User); const authMiddleware async (req, res, next) { try { const token req.headers.authorization?.replace(Bearer , ); if (!token) { return res.status(401).json({ message: 未登录或登录已过期 }); } const decoded jwt.verify(token, process.env.JWT_SECRET); const user await User.findById(decoded.userId); if (!user) { return res.status(401).json({ message: 用户不存在 }); } req.user user; next(); } catch (err) { return res.status(401).json({ message: 无效的令牌 }); } }; module.exports authMiddleware;参数说明请求头里的 Authorization 格式是Bearer token因此先用replace(Bearer , )去掉前缀取出纯 token。jwt.verify在校验篡改和过期时会抛异常直接走401。findById从数据库查用户并挂到req.user上后续代码可以直接用req.user._id识别当前登录者是哪个用户。process.env.JWT_SECRET是环境变量生产环境必须设置并且足够随机开发环境可以在package.json的同级目录创建.env文件用dotenv加载。挂载到创建文章的接口上router.post(/api/articles, authMiddleware, async (req, res, next) { try { const article new Article({ ...req.body, author: req.user._id, }); await article.save(); res.status(201).json(article); } catch (err) { next(err); } });authMiddleware在这里的作用是保证只有登录用户才能发布文章。如果只想让管理员发文章可以在authMiddleware之后再加一个adminOnly中间件检查req.user.role admin。5.2 用户注册与登录JWT 签发逻辑注册接口其实只有一步创建用户并设置密码router.post(/api/auth/register, async (req, res, next) { try { const { username, email, password, role } req.body; const user new User({ username, email, role: role || author }); user.setPassword(password); await user.save(); res.status(201).json({ message: 注册成功 }); } catch (err) { next(err); } });登录接口负责校验密码并签发 JWTrouter.post(/api/auth/login, async (req, res, next) { try { const { username, password } req.body; const user await User.findOne({ username }); if (!user || !user.validatePassword(password)) { return res.status(401).json({ message: 用户名或密码错误 }); } const token jwt.sign({ userId: user._id, role: user.role }, process.env.JWT_SECRET, { expiresIn: 7d, }); res.json({ token, user: { id: user._id, username: user.username, role: user.role }, }); } catch (err) { next(err); } });expiresIn: 7d表示令牌有效期 7 天超过 7 天后前端需要引导用户重新登录。JWT 被设计成无状态服务端不保存 session所以“强制退出登录”在纯 JWT 方案里是做不到的——除非引入黑名单机制但那已经超出博客系统范畴了。对于这个项目7 天过期是可以接受的代价是如果用户密码泄露令牌最长还有 7 天有效。真要更安全口头建议是缩短到 1 天加 refresh token 机制但不要为了一个博客管理系统把复杂度拉满。5.3 文件上传与图片处理中间件选型封面图片是博客系统的刚需我用multer做文件上传这是 Express 生态里最成熟的方案它把上传文件从req.files里暴露出来配合sharp做图片压缩可以控制封面图体积。安装两个包npm install multer sharp上传接口的典型写法// routes/upload.js const multer require(multer); const sharp require(sharp); const path require(path); const storage multer.diskStorage({ destination: (req, file, cb) cb(null, public/uploads), filename: (req, file, cb) { const unique Date.now() - Math.round(Math.random() * 1e9); cb(null, unique path.extname(file.originalname)); }, }); const upload multer({ storage, limits: { fileSize: 5 * 1024 * 1024 }, fileFilter: (req, file, cb) { const allowed [image/jpeg, image/png, image/webp]; if (!allowed.includes(file.mimetype)) { return cb(new Error(仅支持 JPEG、PNG、WebP 格式)); } cb(null, true); }, }); router.post(/api/upload/cover, authMiddleware, upload.single(cover), async (req, res, next) { try { const filePath req.file.path; const outputPath filePath.replace(path.extname(filePath), .webp); await sharp(filePath).resize(1200, 630).webp({ quality: 80 }).toFile(outputPath); res.json({ url: /uploads/ path.basename(outputPath) }); } catch (err) { next(err); } });参数说明fileSize: 5 * 1024 * 1024限制单张图片不能超过 5MB超出后 multer 会返回错误。fileFilter从 MIME 类型层面拦截非图片文件。文件名用时间戳加随机数拼接避免中文文件名和空格造成 URL 编码问题。sharp把上传的图片压缩成 1200x630 的 WebP体积通常能减少 60% 以上。存储路径不建议放在项目根目录下的uploads里最好放public/uploads并通过app.use(express.static(public))暴露出去否则客户端无法通过 URL 访问图片。5.4 错误处理中间件最后一个 app.useExpress 的错误处理中间件长着四个参数这有个业内调侃的说法叫作“不看参数数量就挂不上”因为express是靠参数个数识别错误处理中间件的。它必须挂在所有路由之后// middlewares/errorHandler.js const errorHandler (err, req, res, next) { const statusCode err.status || 500; res.status(statusCode).json({ message: err.message || 服务器内部错误, stack: process.env.NODE_ENV production ? undefined : err.stack, }); }; module.exports errorHandler;然后在app.js里最后一行挂载const errorHandler require(./middlewares/errorHandler); app.use(errorHandler);逻辑说明开发环境下stack字段能打印完整错误调用栈生产环境置为undefined避免泄露网络路径和模块结构。这个中间件统一收口所有路由里next(err)传出的异常如果你不在最后挂它任何一处数据库操作抛错都会导致进程崩溃并返回一张 HTML 错误页。6. 避坑与常见问题排查安装、运行、数据三层视角的踩坑记录6.1 安装层npm 与 MongoDB 的高频翻车现场现象执行npm install报npm ERR! code ERESOLVE依赖树解析失败。原因这是 npm 7 之后对 peerDependencies 的严格校验导致的常见于某些包版本之间不兼容。比如全局安装了某个版本的 Express项目里又装了一个不兼容的版本npm 就会罢工。解决先尝试npm install --legacy-peer-deps让 npm 跳过 peerDependency 冲突检查。如果还不行删除node_modules和package-lock.json后重新安装。我在实际项目中遇到过mongoose与mongodb-driver版本不匹配导致的连接失败这类问题直接看项目 package.json 里锁定的版本号再去 npm 官网比对两个包的 peerDependencies 范围。现象本地能连 MongoDB但代码里mongoose.connect一直超时报Server selection timed out。原因数据库服务没启动或者连接字符串里的主机名写成了localhost而 MongoDB 绑定的是 IPv6 地址。解决开发环境统一用127.0.0.1而不是localhost因为有些操作系统会把localhost解析成::1MongoDB 默认监听的是0.0.0.0两者在某些网络栈下会错开。再验证服务是否真的在跑mongosh --eval db.runCommand({ ping: 1 })能返回ok: 1说明数据库层面没问题。6.2 运行层Express 中间件顺序就是命根子现象请求打到接口返回 404但路由文件里明明写了这个路径。原因路由文件挂载顺序错误。如果app.use(/api, articleRouter)写在app.use(express.json())之前请求体还没被解析POST 接口拿到的是undefined。另一个经典错误是把错误处理中间件挂在了路由之前导致next(err)进了错误处理但路由还没匹配完。解决中间件挂载顺序从上到下依次是express.json()→cors()→ 静态文件目录 → 路由 → 404 兜底 → 错误处理中间件。这个顺序不要打乱否则就会出现“接口明明存在但请求不达路由”的诡异现象。6.3 数据层MongoDB 查询聚合与删除操作的血泪经验现象用Article.deleteOne({ _id: id })删文章成功了但评论列表里还有对应文章的历史评论前端渲染详情页时一加载就报空指针。原因MongoDB 没有外键级联删除这是它与 SQL 数据库最大的心智差异。删除文章不会自动删评论。解决删除文章的接口里手动补一条删除评论的语句const articleId req.params.id; await Article.deleteOne({ _id: articleId }); await Comment.deleteMany({ article: articleId });现象db.articles.find({ tags: Nodejs })查不出刚创建的标签为nodejs的文章因为Schema 里lowercase: true把标签转换成了小写但查询条件里写的是首字母大写。原因查询时不会自动调用 Schema 的lowercase转换它只作用于写入阶段。解决查询前手动tags.toLowerCase()或者干脆统一用$regex: new RegExp(^ tag $, i)做不区分大小写的精确匹配。正则的i标志表示忽略大小写这是处理用户输入查询条件时的默认做法。现象Article.findById(id)返回 null但用 Compass 看数据明明存在。原因前端传来的id不是合法的 ObjectId 字符串可能是 undefined带了个空格或者是被截断的 23 位短字符串。Mongoose 对格式不合法的 id 会直接返回 null 而不是抛异常导致你排查时一脸懵。解决先用 Mongoose 内置的类型校验mongoose.Types.ObjectId.isValid(id)返回 false 时直接返回 400 错误不要让非法 id 进到数据库查询层。6.4 前后端联调跨域与请求体格式的两个细节现象前端用 axios 发起 POST 请求后端收到了但req.body是空对象。原因前端没设置Content-Type: application/jsonaxios 默认对普通对象用的是application/x-www-form-urlencoded而后端只用了express.json()解析 JSON 格式没有express.urlencoded()兜底。解决axios 请求时显式指定axios.post(/api/auth/login, data, { headers: { Content-Type: application/json }, });现象前端登录后存储了 token但刷新页面后接口全部 401。原因axios 拦截器里没把 token 塞到请求头或者把 token 存在了sessionStorage里刷新标签页后 sessionStorage 还在但浏览器在新标签页打开时 session 不共享。解决用localStorage存 token并在 axios 拦截器里统一加头axios.interceptors.request.use(config { const token localStorage.getItem(token); if (token) { config.headers.Authorization Bearer ${token}; } return config; });7. 部署验证与压测用curl和k6给博客系统做一次体检整套代码写完后部署和验证是很多人最心虚的环节。代码在本地跑得飞起一上服务器就 502核心原因是环境变量缺失、端口冲突、数据库没有守护进程这三个问题。部署我不展开讲 Nginx 配置只讲做完部署后必须执行的验证步骤——这比教程里铺天盖地的配置片段更值钱。先验证健康检查接口。确保你的app.js里有这样一条路由router.get(/api/health, (req, res) res.json({ status: ok, time: Date.now() }));部署完成后运行curl http://你的服务器IP:3000/api/health期望返回{status:ok}且time字段是最近几秒内的毫秒时间戳。这一步能同时验证进程活着、端口互通、Nginx 反向代理没配错。接下来验证鉴权链路用一段完整的curl命令模拟登录并获取 tokencurl -X POST http://你的服务器IP:3000/api/auth/login \ -H Content-Type: application/json \ -d {username: admin, password: admin123} \ -c cookies.txt返回结果里应该包含token字段把它复制到下面的命令里curl -X POST http://你的服务器IP:3000/api/articles \ -H Content-Type: application/json \ -H Authorization: Bearer 替换成上面的token \ -d {title: 部署验证文章, content: 测试内容, summary: 测试摘要}返回 201 和文章对象说明数据库写入正常、鉴权中间件没有误伤合法请求。接着用GET拉取列表接口验证分页参数curl http://你的服务器IP:3000/api/articles?page1pageSize5验证total字段和你刚写入的文章数量一致——这里特别提醒分页参数经常因为手滑写成了pageSize0Mongoose 的.limit(0)会返回空数组而不是报错很多人排查半天以为接口坏了其实是参数传错了。我在本地测试里加了一条规则前端传入的pageSize一律用Math.min(100, Math.max(1, n))夹在 1 到 100 之间。压测部分如果你用的是k6一个开源压测工具最小脚本长这样// load-test.js import http from k6/http; import { check } from k6; export const options { vus: 20, duration: 30s, }; export default function () { const res http.get(http://127.0.0.1:3000/api/articles?page1pageSize10); check(res, { status is 200: (r) r.status 200, response time 500ms: (r) r.timings.duration 500, }); }k6 run load-test.jsvus: 20表示 20 个虚拟用户并发duration: 30s持续压 30 秒。压测前先把 MongoDB 服务端和 Node 进程的日志都开着如果接口延迟普遍超过 500ms大概率是缺少索引导致的集合扫描。对博客系统最有价值的索引是文章表的{ status: 1, createdAt: -1 }复合索引MySQL 里的查询优化经验在 MongoDB 里同样适用。压测和验证做完我最后提一个自己吃过亏的习惯上线前务必在app.js里打印启动日志至少包含监听端口和数据库状态。很多生产事故不是代码写错而是换了一台服务器后数据库地址忘了改、环境变量没带过去却毫无感知。日志是玄学排查后唯一的后悔药别省。希望这篇从环境搭建到接口验证的完整记录能帮你在做博客管理系统时少走几步弯路。踩坑不可怕可怕的是同一个坑踩完还不留日志下次换台机器接着踩——把这篇里的验证命令当成固定动作你会在后续的全栈项目里省很多时间。本文还有配套的精品资源点击获取
