微信小程序全栈开发实战：从零构建名片管理系统

简介：微信小程序开发已成为连接用户与服务的重要技术，其核心在于前后端分离架构与数据通信。理解其原理，需要掌握前端界面构建、后端API设计以及数据库操作等关键技术。这些技术共同支撑了现代Web应用的高效运行与数据安全。在工程实践中，通过实现一个具体的业务系统，如名片管理系统，可以深入理解用户认证、数据CRUD、文件上传等通用模块的实现细节。本项目以Node.js + Koa2 + MySQL为技术栈，详细拆解了从环境搭建、核心功能实现到生产部署的全过程，并重点融入了JWT鉴权与OCR集成等热词技术，为开发者提供了一个完整的全栈学习范例。

1. 项目概述：一个能跑起来的微信小程序名片管理系统

最近在整理硬盘，翻出来一个老项目——“微信小程序名片管理系统源码数据库.zip”。这名字听起来就很有年代感，一个典型的“毕业设计”或“个人练手”项目集合。但你别小看它，这种项目麻雀虽小，五脏俱全，非常适合想入门微信小程序全栈开发的朋友。它通常包含了前端小程序代码、后端服务（可能是PHP、Java或Node.js）以及一个数据库文件（比如MySQL的.sql文件）。今天，我就以这个“压缩包”为引子，带你从零开始，把它变成一个真正能在你电脑上跑起来，甚至能部署上线的完整系统。我们不光要让它跑起来，更要拆解清楚每一个环节的设计思路、技术选型和那些新手最容易踩的坑。

这个系统的核心逻辑很简单：用户通过微信小程序扫描或手动添加名片，信息存入数据库，后续可以分类、搜索、管理。但实现起来，就涉及到微信小程序前端界面与交互、后端API接口设计、数据库表结构规划以及前后端数据通信。整个过程，就是一个微型的全栈开发实战。无论你是想学习小程序开发，还是想了解一个完整应用的后台是如何运作的，这个拆解过程都会给你带来实实在在的收获。

2. 核心需求与功能模块拆解

拿到一个项目源码包，第一步不是急着运行，而是先理解它要做什么。一个名片管理系统，核心需求无非是围绕“名片”这个实体进行增删改查（CRUD），并附加一些提升体验的功能。

2.1 核心实体与字段分析

名片（Business Card）是系统的核心实体。一个设计良好的名片表，应该包含哪些字段呢？这直接决定了系统的实用性和扩展性。

• 基础身份信息：name（姓名）、company（公司）、title（职位）。这是名片的三要素。
• 多维联系方式：phone（电话）、email（邮箱）、wechat（微信）、address（地址）。这里要注意，电话可能有多个（工作电话、私人电话），邮箱也可能有多个。在简单的实现中，我们可以用单个字段；但如果考虑扩展性，更好的设计是为联系方式建立单独的表，与名片主表关联。
• 媒体与附件：avatar（头像）。通常存储的是图片在服务器上的URL地址，而不是直接存图片文件。小程序端上传图片到后端，后端将文件保存到云存储或服务器目录，并将可访问的URL返回，存入数据库。
• 系统元信息：id（主键，自增）、create_time（创建时间）、update_time（更新时间）、user_id（所属用户ID）。user_id是关键，它关联到用户表，实现了数据隔离，确保每个用户只能看到和管理自己的名片。
• 分类与标签：category（分类）或通过关联表实现标签（Tag）功能。方便用户对名片进行分组管理，例如“客户”、“供应商”、“同事”。

在查看源码中的数据库SQL文件时，重点就是看business_card这张表的结构。如果它缺少user_id，那说明这是一个单用户系统，或者权限控制存在缺陷。如果所有字段都挤在一张表里，可能不利于复杂查询，但作为入门项目，完全可以接受。

2.2 前后端功能模块划分

基于核心实体，我们可以将系统划分为清晰的前后端模块：

前端（微信小程序）模块：

1. 用户认证模块：调用wx.login获取code，向后端换取自定义登录态（如token）。这是小程序访问后端数据的“门票”。
2. 名片列表模块：以列表或卡片形式展示所有名片，支持下拉刷新、上拉加载更多。通常会有搜索框和分类筛选器。
3. 名片详情模块：点击某张名片后进入，展示所有详细信息。提供编辑和删除按钮。
4. 新增/编辑名片模块：一个表单页，包含多个输入框（姓名、公司、电话等）和图片上传组件。提交时调用后端API。
5. 扫描名片模块：集成小程序的相机API，拍照后，调用后端的OCR（光学字符识别）接口解析图片中的文字，自动填充表单。这是提升体验的关键功能。
6. 我的/设置模块：管理用户个人信息、分类标签等。

后端（服务端）模块：

1. 用户鉴权接口：/api/auth/login，处理wx.login的code，验证后生成并返回token。
2. 名片CRUD接口组：
   • POST /api/card- 新增名片
   • GET /api/card- 获取名片列表（支持分页、筛选、搜索）
   • GET /api/card/:id- 获取单张名片详情
   • PUT /api/card/:id- 更新名片
   • DELETE /api/card/:id- 删除名片
3. 文件上传接口：POST /api/upload，接收小程序端上传的图片文件，保存到指定位置，返回文件URL。
4. OCR识别接口：POST /api/ocr，接收名片图片，调用第三方OCR服务（如百度AI、腾讯云OCR）或使用开源库解析，返回结构化数据。
5. 数据库操作层：封装所有对数据库（如MySQL）的增删改查操作。

注意：很多教学源码为了简化，可能将后端逻辑直接写在了小程序的云函数里，或者使用了小程序云开发。这确实是快速开发的方案，但不利于理解传统的、分离式的Web服务架构。我们今天的讨论基于更通用的前后端分离模式。

3. 技术栈选型与环境搭建实操

“源码数据库.zip”里可能包含了多种技术栈的组合。我们假设一个最经典、学习资料最丰富的组合：微信小程序（前端） + Node.js + Koa2（后端） + MySQL（数据库）。

3.1 前端：微信小程序基础配置

首先，你需要安装微信开发者工具。创建一个新的小程序项目，AppID可以先使用测试号。项目结构通常如下：

miniprogram/ ├── pages/ │ ├── index/ # 名片列表页 │ ├── detail/ # 详情页 │ ├── edit/ # 编辑/新增页 │ └── scan/ # 扫描页 ├── components/ # 自定义组件（如名片卡片） ├── utils/ │ └── request.js # 封装网络请求 ├── app.js # 小程序入口 ├── app.json # 全局配置 └── app.wxss # 全局样式

关键一步是封装网络请求。在utils/request.js中，我们需要统一处理URL、token、错误码。

// utils/request.js const BASE_URL = 'http://localhost:3000'; // 你的后端服务地址 const request = (options) => { // 从本地存储获取token const token = wx.getStorageSync('token'); return new Promise((resolve, reject) => { wx.request({ url: BASE_URL + options.url, method: options.method || 'GET', data: options.data || {}, header: { 'Content-Type': 'application/json', 'Authorization': token ? `Bearer ${token}` : '' // 将token放入请求头 }, success: (res) => { if (res.statusCode === 200) { // 假设后端统一返回 { code: 0, data: ..., msg: 'success' } 的格式 if (res.data.code === 0) { resolve(res.data.data); } else { // 业务逻辑错误，如 token 过期 wx.showToast({ title: res.data.msg, icon: 'none' }); if (res.data.code === 401) { // token无效，跳转到登录页或重新登录 wx.navigateTo({ url: '/pages/login/login' }); } reject(res.data); } } else { // HTTP状态码错误 wx.showToast({ title: `请求失败: ${res.statusCode}`, icon: 'none' }); reject(res); } }, fail: (err) => { wx.showToast({ title: '网络连接失败', icon: 'none' }); reject(err); } }); }); }; module.exports = request;

这个封装拦截了所有请求，自动添加token，并统一处理了成功和失败的逻辑，让业务代码更简洁。

3.2 后端：Node.js + Koa2 服务搭建

在后端目录，初始化项目并安装核心依赖。

mkdir server && cd server npm init -y npm install koa koa-router koa-bodyparser koa-static koa-jwt mysql2 dotenv npm install -D nodemon

• koa: Web框架。
• koa-router: 路由中间件。
• koa-bodyparser: 解析POST请求体。
• koa-static: 托管静态文件（如图片）。
• koa-jwt: 用于生成和验证JWT（JSON Web Token）令牌。
• mysql2: 连接和操作MySQL数据库。
• dotenv: 从.env文件加载环境变量。
• nodemon: 开发热重载工具。

创建入口文件app.js：

// server/app.js const Koa = require('koa'); const Router = require('koa-router'); const bodyParser = require('koa-bodyparser'); const static = require('koa-static'); const jwt = require('koa-jwt'); const path = require('path'); require('dotenv').config(); const app = new Koa(); const router = new Router(); // 中间件 app.use(bodyParser()); // 解析请求体 app.use(static(path.join(__dirname, 'public'))); // 托管public目录下的静态资源 // 错误处理中间件 app.use(async (ctx, next) => { try { await next(); } catch (err) { ctx.status = err.status || 500; ctx.body = { code: ctx.status, msg: err.message }; ctx.app.emit('error', err, ctx); // 触发错误事件 } }); // 公开路径（无需token） router.post('/api/auth/login', authController.login); router.post('/api/upload', uploadController.upload); // 上传可能也需要先登录，这里仅为示例 // JWT 鉴权中间件，从此以下所有路由需要token app.use(jwt({ secret: process.env.JWT_SECRET }).unless({ path: [/^\/api\/auth/] })); // 需要鉴权的路由 router.get('/api/card', cardController.list); router.post('/api/card', cardController.create); // ... 其他CRUD路由 app.use(router.routes()).use(router.allowedMethods()); const PORT = process.env.PORT || 3000; app.listen(PORT, () => { console.log(`Server is running on http://localhost:${PORT}`); });

这里的关键是使用koa-jwt中间件。所有路由在默认情况下都需要有效的JWT Token才能访问，除非使用unless方法排除了登录等公开接口。Token通常由前端在登录成功后保存在wx.setStorageSync('token', res.token)中，并在每次请求时通过Authorization头发送。

3.3 数据库：MySQL初始化与连接

在MySQL中创建一个数据库，例如business_card_db。然后运行源码包中提供的.sql文件来创建表。如果没有，你需要根据分析自行创建。一个简化的business_cards表创建语句如下：

CREATE TABLE `business_cards` ( `id` int(11) NOT NULL AUTO_INCREMENT, `user_id` varchar(100) NOT NULL COMMENT '关联用户ID，通常用微信OpenID', `name` varchar(50) NOT NULL, `company` varchar(100) DEFAULT NULL, `title` varchar(50) DEFAULT NULL, `phone` varchar(20) DEFAULT NULL, `email` varchar(100) DEFAULT NULL, `wechat` varchar(50) DEFAULT NULL, `address` varchar(255) DEFAULT NULL, `avatar` varchar(500) DEFAULT NULL COMMENT '头像URL', `category` varchar(50) DEFAULT NULL, `create_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, `update_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_user_id` (`user_id`), -- 为user_id建立索引，加速查询 KEY `idx_name` (`name`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='名片表';

注意使用了utf8mb4字符集以支持存储Emoji等特殊字符，并为user_id和name创建了索引以提高查询效率。

在后端，我们创建数据库连接工具db.js：

// server/utils/db.js const mysql = require('mysql2/promise'); // 使用Promise版本 require('dotenv').config(); const pool = mysql.createPool({ host: process.env.DB_HOST || 'localhost', user: process.env.DB_USER || 'root', password: process.env.DB_PASSWORD || 'yourpassword', database: process.env.DB_NAME || 'business_card_db', waitForConnections: true, connectionLimit: 10, // 连接池大小 queueLimit: 0 }); module.exports = pool;

使用连接池（createPool）而不是单连接，可以避免频繁创建和销毁连接的开销，提升性能。

4. 核心功能实现与代码解析

环境搭好，接下来就是实现核心业务逻辑。我们挑两个最典型的场景：用户登录鉴权和名片增删改查。

4.1 用户登录与JWT鉴权流程

小程序登录流程是固定的：前端调用wx.login获取临时凭证code，将这个code发送到我们自己的后端服务器，后端再用code、小程序的AppID和AppSecret去微信接口服务换取该用户的唯一标识openid和会话密钥session_key。

后端登录控制器 (authController.js)：

const axios = require('axios'); const jwt = require('jsonwebtoken'); const pool = require('../utils/db'); exports.login = async (ctx) => { const { code } = ctx.request.body; if (!code) { ctx.throw(400, 'Code is required'); } // 1. 向微信服务器换取 openid 和 session_key const appid = process.env.WX_APPID; const secret = process.env.WX_SECRET; const url = `https://api.weixin.qq.com/sns/jscode2session?appid=${appid}&secret=${secret}&js_code=${code}&grant_type=authorization_code`; try { const response = await axios.get(url); const { openid, session_key, errcode, errmsg } = response.data; if (errcode) { ctx.throw(400, `WeChat API error: ${errmsg}`); } // 2. 业务处理：根据openid查找或创建用户 const [users] = await pool.execute('SELECT * FROM users WHERE openid = ?', [openid]); let userId; if (users.length === 0) { // 新用户，插入数据库 const [result] = await pool.execute( 'INSERT INTO users (openid, created_at) VALUES (?, NOW())', [openid] ); userId = result.insertId; } else { userId = users[0].id; } // 3. 生成JWT Token，将用户id和openid存入token const token = jwt.sign( { userId, openid }, process.env.JWT_SECRET, { expiresIn: '7d' } // Token有效期7天 ); // 4. 返回token和用户基本信息给前端 ctx.body = { code: 0, msg: 'success', data: { token, userInfo: { userId, openid } } }; } catch (error) { console.error('Login error:', error); ctx.throw(500, 'Internal server error during login'); } };

实操心得：AppSecret是极其敏感的信息，必须放在后端环境变量（.env文件）中，绝对不要写死在前端代码里。前端只需要传code。另外，微信返回的session_key是微信端用于解密用户敏感数据的，后端通常不需要存储它，除非你要做手机号解密等操作。

4.2 名片CRUD与数据库交互

以创建名片和获取名片列表为例，展示如何安全地进行数据库操作。

创建名片 (cardController.js- create)：

exports.create = async (ctx) => { // 从JWT Token中解析出的用户信息（由koa-jwt中间件挂载到ctx.state） const { userId } = ctx.state.user; const cardData = ctx.request.body; // 简单的数据验证 if (!cardData.name) { ctx.throw(400, 'Name is required'); } // 构造SQL插入语句，确保user_id来自token，防止越权创建 const sql = `INSERT INTO business_cards (user_id, name, company, title, phone, email, wechat, address, avatar, category) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`; const params = [ userId, cardData.name, cardData.company || null, cardData.title || null, cardData.phone || null, cardData.email || null, cardData.wechat || null, cardData.address || null, cardData.avatar || null, cardData.category || null ]; try { const [result] = await pool.execute(sql, params); ctx.body = { code: 0, msg: 'Card created successfully', data: { id: result.insertId } }; } catch (error) { console.error('Create card error:', error); // 处理重复插入等数据库错误 if (error.code === 'ER_DUP_ENTRY') { ctx.throw(409, 'Card already exists'); } ctx.throw(500, 'Failed to create card'); } };

获取名片列表 (cardController.js- list)：

exports.list = async (ctx) => { const { userId } = ctx.state.user; const { page = 1, pageSize = 10, keyword, category } = ctx.query; // 从查询参数获取分页和筛选条件 // 计算偏移量 const offset = (page - 1) * pageSize; // 构建查询条件和参数 let whereClause = 'WHERE user_id = ?'; const queryParams = [userId]; if (keyword) { whereClause += ' AND (name LIKE ? OR company LIKE ? OR phone LIKE ?)'; const likeKeyword = `%${keyword}%`; queryParams.push(likeKeyword, likeKeyword, likeKeyword); } if (category) { whereClause += ' AND category = ?'; queryParams.push(category); } // 查询总条数（用于前端分页器） const countSql = `SELECT COUNT(*) as total FROM business_cards ${whereClause}`; const [countResult] = await pool.execute(countSql, queryParams); const total = countResult[0].total; // 查询当前页数据 const dataSql = `SELECT * FROM business_cards ${whereClause} ORDER BY update_time DESC LIMIT ? OFFSET ?`; const dataParams = [...queryParams, parseInt(pageSize), offset]; const [rows] = await pool.execute(dataSql, dataParams); ctx.body = { code: 0, msg: 'success', data: { list: rows, pagination: { page: parseInt(page), pageSize: parseInt(pageSize), total, totalPages: Math.ceil(total / pageSize) } } }; };

注意事项：1.SQL注入防护：我们始终使用参数化查询（?占位符），而不是拼接字符串，这是安全底线。2.权限校验：每个查询都强制带上user_id = ?条件，这是实现数据隔离的核心，确保用户只能操作自己的数据。3.分页：一定要做分页，尤其是数据量可能增长时。LIMIT ? OFFSET ?是标准做法，同时返回总数便于前端显示总页数。

5. 高级功能实现：图片上传与OCR集成

一个现代化的名片管理系统，手动输入太麻烦。核心体验提升点在于拍照扫描和自动填充。

5.1 小程序端图片上传

小程序端使用wx.chooseImage选择图片，然后使用wx.uploadFile上传。

// pages/scan/scan.js - 选择并上传图片 Page({ data: { tempFilePath: '' }, chooseImage() { wx.chooseImage({ count: 1, sizeType: ['compressed'], // 压缩图 sourceType: ['album', 'camera'], success: (res) => { const tempFilePath = res.tempFilePaths[0]; this.setData({ tempFilePath }); this.uploadImage(tempFilePath); } }); }, uploadImage(filePath) { const token = wx.getStorageSync('token'); wx.uploadFile({ url: 'http://localhost:3000/api/upload', filePath: filePath, name: 'file', header: { 'Authorization': `Bearer ${token}` }, formData: { 'type': 'avatar' }, // 可传递其他参数 success: (res) => { const data = JSON.parse(res.data); if (data.code === 0) { const imageUrl = data.data.url; // 上传成功，将imageUrl用于名片表单，或调用OCR接口 this.callOcrService(imageUrl); } else { wx.showToast({ title: '上传失败', icon: 'none' }); } }, fail: (err) => { console.error(err); wx.showToast({ title: '网络错误', icon: 'none' }); } }); } });

5.2 服务端文件接收与存储

后端使用koa-bodyparser无法处理文件，需要借助koa-body（或@koa/multer）。这里以koa-body为例。

npm install koa-body

// app.js 中替换 bodyParser const koaBody = require('koa-body'); app.use(koaBody({ multipart: true, // 支持文件上传 formidable: { maxFileSize: 5 * 1024 * 1024, // 限制5MB uploadDir: path.join(__dirname, 'public/uploads'), // 上传目录 keepExtensions: true, // 保留扩展名 } }));

// controller/uploadController.js const path = require('path'); exports.upload = async (ctx) => { // 文件信息在 ctx.request.files.file 中 const file = ctx.request.files.file; if (!file) { ctx.throw(400, 'No file uploaded'); } // 生成一个唯一的文件名，防止覆盖 const ext = path.extname(file.originalFilename); const newFilename = Date.now() + '-' + Math.round(Math.random() * 1E9) + ext; const newPath = path.join('uploads', newFilename); // 相对于静态资源目录的路径 // 移动文件（koa-body已保存，这里主要是重命名逻辑，实际可能需fs.rename） const fs = require('fs').promises; const oldPath = file.filepath; const absoluteNewPath = path.join(__dirname, '../public', newPath); await fs.rename(oldPath, absoluteNewPath); // 返回可访问的URL const fileUrl = `http://localhost:3000/${newPath}`; ctx.body = { code: 0, msg: 'success', data: { url: fileUrl } }; };

5.3 集成OCR服务自动填充

上传图片后，我们可以将图片URL发送到OCR接口。这里以调用百度AI开放平台的通用文字识别（高精度版）为例。

// controller/ocrController.js const axios = require('axios'); exports.recognize = async (ctx) => { const { imageUrl } = ctx.request.body; // 1. 从URL下载图片到Buffer（或直接处理base64） const imageResponse = await axios.get(imageUrl, { responseType: 'arraybuffer' }); const imageBase64 = Buffer.from(imageResponse.data, 'binary').toString('base64'); // 2. 调用百度OCR API const ACCESS_TOKEN = process.env.BAIDU_OCR_TOKEN; // 需提前获取 const ocrUrl = `https://aip.baidubce.com/rest/2.0/ocr/v1/accurate_basic?access_token=${ACCESS_TOKEN}`; const params = new URLSearchParams(); params.append('image', imageBase64); params.append('detect_direction', 'true'); // 检测朝向 const ocrResponse = await axios.post(ocrUrl, params, { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }); // 3. 解析OCR结果 const { words_result } = ocrResponse.data; const text = words_result.map(item => item.words).join('\n'); // 4. （进阶）使用规则或NLP模型从text中提取结构化信息 // 例如：通过正则表达式匹配手机号、邮箱等 const phoneMatch = text.match(/(1[3-9]\d{9})/); const emailMatch = text.match(/([a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\.[a-zA-Z0-9._-]+)/i); const structuredData = { rawText: text, name: '', // 需要更复杂的算法提取 phone: phoneMatch ? phoneMatch[1] : null, email: emailMatch ? emailMatch[1] : null, company: '', title: '' }; // 5. 返回结构化的名片信息给前端 ctx.body = { code: 0, msg: 'success', data: structuredData }; };

实操心得：OCR识别出的是一段文本，如何从中精准提取“姓名”、“公司”、“职位”是真正的难点。简单的规则匹配（正则表达式）效果有限。对于生产环境，可以考虑：1. 使用百度、腾讯云等提供的名片识别专用API，它们直接返回结构化字段。2. 训练一个简单的命名实体识别（NER）模型。3. 设计一个交互界面，将OCR文本和高亮字段对应，让用户辅助确认和修正。

6. 项目部署与上线前关键配置

让项目在本地运行只是第一步，要真正能用，还需要部署到服务器，并完成一系列生产环境配置。

6.1 后端服务生产环境部署

不建议直接用node app.js运行。使用进程管理工具PM2，可以保证服务稳定运行，崩溃后自动重启。

npm install -g pm2 pm2 start app.js --name business-card-api pm2 save pm2 startup # 设置开机自启

关键生产配置（.env.production文件）：

NODE_ENV=production PORT=3000 JWT_SECRET=your_super_strong_jwt_secret_here # 务必使用强随机字符串 DB_HOST=your_production_db_host DB_USER=your_production_db_user DB_PASSWORD=your_production_db_password DB_NAME=your_production_db_name WX_APPID=your_wechat_appid WX_SECRET=your_wechat_appsecret BAIDU_OCR_TOKEN=your_baidu_ocr_token

• JWT_SECRET：这是签名令牌的密钥，一旦泄露，攻击者可以伪造任意用户的token。必须使用强密码生成器生成，并妥善保管。
• 数据库连接：生产环境数据库应与应用服务器分离，使用内网地址连接，并设置强密码。
• HTTPS：小程序要求后端接口必须是HTTPS。你需要在服务器（如Nginx）上配置SSL证书。可以使用Let‘s Encrypt免费申请。

6.2 微信小程序配置与提审

1. 服务器域名配置：在小程序管理后台 -> 开发 -> 开发设置 -> 服务器域名中，配置request合法域名（你的后端API地址，如https://api.yourdomain.com）和uploadFile合法域名（文件上传地址）。
2. AppID和AppSecret：使用正式AppID，并在后台获取AppSecret，填入后端环境变量。
3. 体验版与提审：在开发者工具上传代码，在管理后台设置为体验版，供测试。完成测试后，提交审核，填写清晰的功能描述，通常个人开发的名片管理工具审核通过率较高。

6.3 数据库备份与安全

• 定期备份：使用mysqldump命令或面板工具定期备份数据库。

  mysqldump -u username -p database_name > backup_$(date +%Y%m%d).sql

• 权限最小化：为后端应用创建独立的数据库用户，只授予其必要的INSERT,SELECT,UPDATE,DELETE权限，不要用root账户。
• SQL注入（再次强调）：坚持使用参数化查询，这是最重要的安全防线。

7. 常见问题排查与性能优化

在实际开发和运行中，你肯定会遇到各种问题。这里记录一些典型问题的排查思路。

7.1 连接与跨域问题

问题现象	可能原因	解决方案
小程序网络请求报fail	1. 后端服务未启动 2. 服务器防火墙未开放端口 3. 域名未配置	1. 检查pm2 list或服务状态 2. 开放服务器安全组/防火墙端口（如3000） 3. 在小程序后台配置合法域名
请求返回403或跨域错误	1. 后端未设置CORS头部 2. 复杂请求（如带自定义头Authorization）未处理	在后端Koa中增加CORS中间件： npm install @koa/cors 并在app.js中app.use(cors())
上传图片失败，返回404	1. 上传接口路由不存在 2.koa-body配置不正确 3. 静态资源目录未正确配置	1. 检查路由 2. 确认koa-body的multipart: true 3. 确认koa-static中间件托管了上传目录

7.2 数据库与性能问题

问题现象	可能原因	解决方案
数据库连接超时或报ER_CON_COUNT_ERROR	1. 连接数过多，未使用连接池或连接池过小 2. 连接未正确释放	1. 使用连接池并适当调大connectionLimit（如50） 2. 确保每次查询后，连接池会自动回收连接（使用mysql2/promise无需手动释放）
列表查询随着数据量变大越来越慢	1. 未对常用查询条件（如user_id,name）建立索引 2. 一次性查询全部数据，未分页	1. 为WHERE和ORDER BY子句中的字段添加索引 2.强制实施分页，即使前端不要求，后端也要限制单次返回数量（如LIMIT 1000）
并发上传时服务器卡死	1. 文件同步处理，阻塞事件循环 2. 磁盘IO成为瓶颈	1. 使用异步文件操作（fs.promises） 2. 考虑使用对象存储服务（如腾讯云COS、阿里云OSS），将文件上传压力转移到云服务

7.3 小程序端特定问题

• wx.login和getUserInfo：新版小程序获取用户头像昵称已改为<button open-type="getUserInfo">和getUserProfileAPI，注意区分登录和获取用户信息的流程。
• 真机预览白屏：检查app.json中页面路径是否正确；检查网络请求域名是否在真机调试模式下已勾选“不校验合法域名”；使用开发者工具的“真机调试”功能查看具体错误。
• 图片显示问题：小程序中的图片链接必须是HTTPS，且域名已加入downloadFile合法域名列表。

这个从“源码压缩包”到“可运行系统”的完整过程，几乎涵盖了一个小型Web应用从开发到上线的所有核心环节。每个步骤里都有选择，也有陷阱。我的建议是，不要只满足于让它跑起来。多问几个为什么：为什么用JWT不用Session？为什么连接池大小是10？为什么字段要建索引？把这些问题的答案搞明白，你从这个项目中获得的经验值会翻倍。最后，试着给它加点新功能，比如给名片加标签、按标签筛选、导出为vCard格式，或者做一个简单的数据统计图表，挑战一下自己，这个项目就真正变成你的了。

本文还有配套的精品资源，点击获取