1. 从一次批量上传需求说起
Nodejs 图片上传这件事，单看每一步都不复杂，难的是把「表单解析 → 文件落盘 → 链接入库」串成一条能一次跑通的链路。我这次的需求很具体：客户端一次选多张图，服务端接收后存到本地目录，再把可访问的图片链接写进 Mongodb 数据库，最后返回给前端一个链接数组。听起来像常规操作，但真动手时会遇到几个典型卡点：multer 的array和fields到底怎么选、落盘文件名怎么防重名、$addToSet配$each批量插入时为什么有时只进了一条、以及返回的链接前缀到底该用哪个地址。
这篇就围绕 Nodejs 图片上传到 Mongodb 数据库的完整链路来写，工具锁定multer+mongoose+express，交付可直接复制的 multer 配置、Mongodb 连接串、Schema 骨架，以及一条 curl 上传验证命令。适合已经会写基础 Express 路由、但想把上传闭环做扎实的开发者。另外我会把 TaoToken 的配置放在前置章节，因为后面验证模型对话、生成图片描述这类扩展动作时，一个统一的 API Key 入口能省不少事。
先说清楚整体数据流：客户端multipart/form-data提交 → multer 中间件解析并写入磁盘 → 路由拿到req.files拼出访问链接 → mongoose 把链接数组更新进文档 → 返回 JSON。下面按这个顺序拆。
2. TaoToken 前置配置：统一 API Key 入口
在写上传代码之前，先把 TaoToken 的配置做掉。原因很实际：图片入库之后，你大概率会想加一步「自动生成图片描述」或者「用模型校验图片内容」，这些都要调模型接口。与其到时候到处找 Key，不如现在就把入口理清。
TaoToken 的定位是统一的模型调用入口，官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 基址是 https://taotoken.net/api 。你需要先拿到 API Key，入口在控制台的 API Keys 页面：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。拿到之后建议直接写进环境变量，别硬编码进仓库。
# .env 文件，别提交到 git TAOTOKEN_API_KEY=sk-你的key TAOTOKEN_BASE_URL=https://taotoken.net/apiNodejs 里读取用dotenv：
// config/env.js require('dotenv').config(); module.exports = { apiKey: process.env.TAOTOKEN_API_KEY, baseUrl: process.env.TAOTOKEN_BASE_URL || 'https://taotoken.net/api', };如果你后面要接 Claude Code 这类编码工具做长期开发，可以看 Coding Plan 页面：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。想先在网页里试模型对话，入口是 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到参数问题先翻这里。
注意：API Key 只放服务端环境变量，前端代码里出现 Key 等于泄露。上传接口本身不需要 Key，Key 是给后续模型调用用的。
3. 可复制的 multer 配置与 Mongodb 连接
这一章是核心，直接给能跑的代码。先装依赖：
npm init -y npm install express multer mongoose dotenv3.1 目录结构与静态托管
上传的文件要能被浏览器访问，所以得把落盘目录做成静态资源。目录建议这样：
project/ ├── app.js ├── config/ │ └── env.js ├── models/ │ └── pictureStore.js ├── routes/ │ └── upload.js └── public/ └── upload/ # 图片落盘目录app.js里挂静态目录：
// app.js const express = require('express'); const path = require('path'); const uploadRouter = require('./routes/upload'); const app = express(); app.use(express.json()); app.use('/static', express.static(path.join(__dirname, 'public'))); app.use('/api', uploadRouter); app.listen(3000, () => console.log('server on 3000'));这样public/upload/xxx.jpg就能通过http://localhost:3000/static/upload/xxx.jpg访问。
3.2 multer 磁盘存储配置
multer 的diskStorage决定文件存哪、叫什么名。文件名一定要防重名，否则并发上传会互相覆盖。用时间戳加随机串最稳：
// routes/upload.js const router = require('express').Router(); const multer = require('multer'); const path = require('path'); const fs = require('fs'); const PictureStore = require('../models/pictureStore'); const uploadDir = path.join(__dirname, '../public/upload'); if (!fs.existsSync(uploadDir)) { fs.mkdirSync(uploadDir, { recursive: true }); } const storage = multer.diskStorage({ destination: function (req, file, cb) { cb(null, uploadDir); }, filename: function (req, file, cb) { const ext = path.extname(file.originalname).toLowerCase(); const unique = Date.now() + '-' + Math.round(Math.random() * 1e9); cb(null, unique + ext); }, }); const upload = multer({ storage: storage, limits: { fileSize: 5 * 1024 * 1024 }, // 单文件 5MB fileFilter: function (req, file, cb) { const allow = ['image/jpeg', 'image/png', 'image/webp', 'image/gif']; if (allow.includes(file.mimetype)) { cb(null, true); } else { cb(new Error('仅支持 jpg/png/webp/gif')); } }, });这里几个参数值得对照一下：
| 参数 | 作用 | 建议值 |
|---|---|---|
destination | 落盘目录 | 绝对路径，避免相对路径踩坑 |
filename | 文件名生成 | 时间戳+随机数+原扩展名 |
limits.fileSize | 单文件大小上限 | 按业务定，5MB 起步 |
fileFilter | 类型白名单 | 只放图片 MIME |
3.3 Mongodb 连接串与 Schema 骨架
连接串用 mongoose 标准写法，本地默认端口 27017：
// models/pictureStore.js const mongoose = require('mongoose'); const MONGO_URI = process.env.MONGO_URI || 'mongodb://127.0.0.1:27017/picture_db'; mongoose.connect(MONGO_URI) .then(() => console.log('mongodb connected')) .catch((err) => console.error('mongodb connect error', err)); const pictureStoreSchema = new mongoose.Schema({ storeId: { type: String, index: true }, isCommon: { type: Boolean, default: false }, pictureUrlArr: { type: [String], default: [] }, createdAt: { type: Date, default: Date.now }, }); module.exports = mongoose.model('PictureStore', pictureStoreSchema);Schema 里pictureUrlArr用字符串数组，配合$addToSet天然去重。storeId加索引是因为后面按店铺查询会频繁用到。
3.4 上传路由与批量入库
路由里用upload.array('file', 20)接收最多 20 张图，字段名必须和前端FormData的 key 一致：
router.post('/uploadImgs', upload.array('file', 20), async function (req, res) { try { const base = process.env.SERVICE_ADDRESS || 'http://localhost:3000/static/upload/'; const arr = (req.files || []).map((f) => base + f.filename); if (arr.length === 0) { return res.status(400).json({ code: 400, msg: '没有收到文件' }); } const filter = req.body.storeId ? { storeId: req.body.storeId } : { isCommon: true }; const doc = await PictureStore.findOneAndUpdate( filter, { $addToSet: { pictureUrlArr: { $each: arr } } }, { upsert: true, new: true } ); res.json({ code: 200, data: arr, total: doc.pictureUrlArr.length }); } catch (err) { res.status(500).json({ code: 500, msg: err.message }); } }); module.exports = router;关键点在于$addToSet配$each：$addToSet保证数组元素不重复，$each让它一次处理整个数组。如果只写$addToSet: { pictureUrlArr: arr }，Mongodb 会把整个数组当成一个元素塞进去，这就是很多人「只进了一条」的原因。upsert: true则保证文档不存在时自动创建。
4. 验证请求与成功结果
代码写完，用 curl 直接验证，不用等前端。准备两张图放在当前目录：
curl -X POST http://localhost:3000/api/uploadImgs \ -F "file=@./a.jpg" \ -F "file=@./b.png" \ -F "storeId=shop_1001"预期返回：
{ "code": 200, "data": [ "http://localhost:3000/static/upload/1710000000000-123456789.jpg", "http://localhost:3000/static/upload/1710000000001-987654321.png" ], "total": 2 }再传一次同样的两张图，total应该还是 2，因为$addToSet去重了。如果total变成 4，说明去重没生效，回去检查是不是漏了$each。
验证落盘：打开public/upload/目录，应该能看到两个文件。验证访问：浏览器直接打开返回的链接，图片能显示就说明静态托管没问题。验证入库：用 mongosh 查一下：
mongosh mongodb://127.0.0.1:27017/picture_db db.picturestores.find({ storeId: 'shop_1001' })到这里，上传到入库的闭环就跑通了。如果你还想在上传后自动生成图片描述，可以拿第 2 章的 Key 调模型对话接口，把图片链接作为上下文传进去，这部分按需扩展。
5. 本篇常见错误排查
上传链路跑不通，八成是下面几个问题。我按出现频率排一下。
报错MulterError: Unexpected field：前端FormData的字段名和upload.array('file', 20)里的'file'不一致。检查前端是不是写成了files或image。字段名必须完全一致。
报错ENOENT: no such file or directory：落盘目录不存在。diskStorage不会自动建目录，必须在启动时用fs.mkdirSync(uploadDir, { recursive: true })创建，或者手动建好public/upload。
文件传上去了但链接 404：静态托管路径和返回链接前缀对不上。app.use('/static', express.static(...))对应链接里的/static/，SERVICE_ADDRESS要拼成http://host:port/static/upload/，少一段都会 404。
Mongodb 里只存了一条链接：$addToSet没配$each。正确写法是{ $addToSet: { pictureUrlArr: { $each: arr } } }，注意$each是嵌在字段值里的对象。
报错MongooseError: Operation buffering timed out：mongoose 没连上数据库。检查MONGO_URI是否正确、Mongodb 服务是否启动。本地默认是mongodb://127.0.0.1:27017/库名，用localhost有时会因 IPv6 解析出问题，建议直接用127.0.0.1。
上传大图报File too large：limits.fileSize设小了。按业务调整，但别不设上限，否则容易被塞满磁盘。
中文文件名乱码：file.originalname在部分客户端下编码异常。稳妥做法是丢弃原名，只用扩展名，也就是第 3.2 节里path.extname的写法。
提示：排查时先看服务端日志的完整堆栈，multer 的错误信息其实很明确，多数是字段名或目录问题。
6. 后续扩展与入口汇总
上传闭环跑通后，常见的下一步是给图片加自动描述、做内容审核、或者批量生成缩略图。这些动作都要调模型接口，所以把 Key 和基址统一管好很关键。接入相关的参数和示例，翻接入文档最省时间：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。想先在网页里试模型效果，用模型对话入口：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。如果你打算把这类能力接进日常编码流程，长期用 Coding Plan 更合适：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。Key 的管理入口始终在 API Keys 页面：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。
最后留一个实操建议：把SERVICE_ADDRESS也放进环境变量，本地用http://localhost:3000/static/upload/，上线换成真实域名。这样同一套代码在本地和线上都能返回正确链接，不用改代码。上传接口的字段名、落盘目录、返回前缀这三处保持一致，整条链路就不会断。
