jiebanke/docs/常见问题.md

常见问题 (FAQ)

本文档收集了结伴客项目开发和使用过程中的常见问题及解决方案。

📋 目录

• 环境搭建问题
• 开发相关问题
• 部署相关问题
• 数据库问题
• API接口问题
• 前端问题
• 小程序问题
• 性能优化问题

🛠️ 环境搭建问题

Q: Node.js版本要求是什么？

A: 项目要求 Node.js 16.x 或更高版本。推荐使用 Node.js 18.x LTS 版本。

# 检查Node.js版本
node --version

# 使用nvm管理Node.js版本
nvm install 18
nvm use 18

Q: 安装依赖时出现权限错误怎么办？

A: 避免使用 sudo 安装npm包，建议配置npm全局目录：

# 创建全局目录
mkdir ~/.npm-global

# 配置npm使用新目录
npm config set prefix '~/.npm-global'

# 添加到环境变量
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Q: MySQL连接失败怎么办？

A: 检查以下几个方面：

1. 确认MySQL服务运行

   # macOS
   brew services start mysql
   
   # Linux
   sudo systemctl start mysql
   
   # Windows
   net start mysql
   

2. 检查连接配置

   // backend/.env
   DB_HOST=localhost
   DB_PORT=3306
   DB_NAME=jiebanke
   DB_USER=root
   DB_PASSWORD=your_password
   

3. 创建数据库

   CREATE DATABASE jiebanke CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   

Q: Redis连接问题如何解决？

A: 确保Redis服务正常运行：

# 启动Redis服务
redis-server

# 测试连接
redis-cli ping
# 应该返回 PONG

💻 开发相关问题

Q: 如何重置数据库？

A: 使用项目提供的重置脚本：

# 方法1：使用npm脚本
cd backend
npm run db:reset

# 方法2：手动执行SQL
mysql -u root -p jiebanke < scripts/init-database.sql

Q: 热重载不工作怎么办？

A: 检查以下配置：

1. 后端热重载

   # 确保使用nodemon
   npm run dev
   
   # 检查nodemon配置
   cat nodemon.json
   

2. 前端热重载

   # 确保Vite配置正确
   npm run dev
   
   # 检查vite.config.ts中的server配置
   

Q: ESLint报错如何解决？

A: 常见解决方案：

# 自动修复可修复的问题
npm run lint:fix

# 检查ESLint配置
cat .eslintrc.js

# 重新安装ESLint依赖
npm install --save-dev eslint @typescript-eslint/parser

Q: 如何调试API接口？

A: 推荐使用以下工具：

1. 使用内置测试脚本

   cd backend
   npm run test:api
   

2. 使用Postman或Insomnia

   • 导入API文档中的接口定义
   • 配置环境变量

3. 使用curl命令

   # 测试登录接口
   curl -X POST http://localhost:3000/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"test@example.com","password":"123456"}'
   

🚀 部署相关问题

Q: Docker部署失败怎么办？

A: 检查以下几个方面：

1. 确认Docker版本

   docker --version
   docker-compose --version
   

2. 检查端口占用

   # 检查端口是否被占用
   lsof -i :3000
   lsof -i :8080
   

3. 查看容器日志

   docker-compose logs backend
   docker-compose logs admin-system
   

Q: Nginx配置问题如何解决？

A: 常见配置问题：

1. 检查配置文件语法

   nginx -t
   

2. 重新加载配置

   nginx -s reload
   

3. 查看错误日志

   tail -f /var/log/nginx/error.log
   

Q: SSL证书配置问题？

A: 使用Let's Encrypt免费证书：

# 安装certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d yourdomain.com

# 自动续期
sudo crontab -e
# 添加：0 12 * * * /usr/bin/certbot renew --quiet

🗄️ 数据库问题

Q: 数据库迁移失败怎么办？

A: 按以下步骤排查：

1. 检查迁移文件

   # 查看迁移状态
   npx sequelize-cli db:migrate:status
   
   # 回滚迁移
   npx sequelize-cli db:migrate:undo
   

2. 手动执行SQL

   -- 查看表结构
   DESCRIBE users;
   
   -- 检查约束
   SHOW CREATE TABLE users;
   

Q: 数据库性能问题如何优化？

A: 常见优化方案：

1. 添加索引

   -- 为常用查询字段添加索引
   CREATE INDEX idx_user_email ON users(email);
   CREATE INDEX idx_created_at ON travel_plans(created_at);
   

2. 查询优化

   -- 使用EXPLAIN分析查询
   EXPLAIN SELECT * FROM users WHERE email = 'test@example.com';
   

3. 配置优化

   # my.cnf
   [mysqld]
   innodb_buffer_pool_size = 1G
   query_cache_size = 256M
   

🔌 API接口问题

Q: 接口返回401未授权错误？

A: 检查JWT token配置：

1. 确认token格式

   // 请求头格式
   Authorization: Bearer <your-jwt-token>
   

2. 检查token有效期

   // 解码token查看过期时间
   const jwt = require('jsonwebtoken');
   const decoded = jwt.decode(token);
   console.log(decoded.exp);
   

Q: 跨域问题如何解决？

A: 配置CORS中间件：

// backend/src/app.js
const cors = require('cors');

app.use(cors({
  origin: ['http://localhost:8080', 'https://admin.jiebanke.com'],
  credentials: true
}));

Q: 文件上传失败怎么办？

A: 检查以下配置：

1. 文件大小限制

   // 增加文件大小限制
   app.use(express.json({ limit: '50mb' }));
   app.use(express.urlencoded({ limit: '50mb', extended: true }));
   

2. 存储路径权限

   # 确保上传目录有写权限
   chmod 755 uploads/
   

🎨 前端问题

Q: 组件样式不生效怎么办？

A: 检查以下几个方面：

1. CSS作用域

   <style scoped>
   /* 组件内样式 */
   </style>
   
   <style>
   /* 全局样式 */
   </style>
   

2. 样式优先级

   /* 使用!important提高优先级 */
   .my-class {
     color: red !important;
   }
   

Q: 路由跳转问题？

A: 常见解决方案：

// 编程式导航
this.$router.push('/path');

// 声明式导航
<router-link to="/path">链接</router-link>

// 带参数跳转
this.$router.push({
  name: 'user',
  params: { id: 123 }
});

Q: 状态管理问题？

A: 使用Pinia进行状态管理：

// stores/user.js
import { defineStore } from 'pinia';

export const useUserStore = defineStore('user', {
  state: () => ({
    userInfo: null
  }),
  actions: {
    setUserInfo(info) {
      this.userInfo = info;
    }
  }
});

📱 小程序问题

Q: 小程序真机调试问题？

A: 常见解决方案：

1. 网络请求问题

   // 确保域名在小程序后台配置
   wx.request({
     url: 'https://api.jiebanke.com/api/v1/users',
     method: 'GET',
     success: (res) => {
       console.log(res.data);
     }
   });
   

2. 权限问题

   // app.json
   {
     "permission": {
       "scope.userLocation": {
         "desc": "你的位置信息将用于小程序位置接口的效果展示"
       }
     }
   }
   

Q: 小程序分包加载问题？

A: 配置分包策略：

// app.json
{
  "pages": ["pages/index/index"],
  "subPackages": [
    {
      "root": "pages/travel",
      "pages": ["list/list", "detail/detail"]
    }
  ]
}

⚡ 性能优化问题

Q: 页面加载慢怎么优化？

A: 常见优化策略：

1. 代码分割

   // 路由懒加载
   const UserProfile = () => import('./components/UserProfile.vue');
   

2. 图片优化

   <!-- 使用WebP格式 -->
   <img src="image.webp" alt="description" loading="lazy">
   

3. 缓存策略

   // 设置HTTP缓存
   app.use(express.static('public', {
     maxAge: '1d'
   }));
   

Q: 数据库查询慢如何优化？

A: 优化建议：

1. 使用索引
2. 避免N+1查询
3. 使用连接查询替代子查询
4. 分页查询大数据集

📞 获取帮助

如果以上FAQ没有解决您的问题，可以通过以下方式获取帮助：

技术支持

• GitHub Issues: 提交问题
• 开发者邮箱: dev@jiebanke.com
• 技术QQ群: 123456789

文档资源

• 开发指南: docs/开发指南.md
• API文档: docs/API接口文档.md
• 部署指南: docs/部署指南.md

社区资源

• 官方论坛: https://forum.jiebanke.com
• 技术博客: https://blog.jiebanke.com
• 视频教程: https://video.jiebanke.com

---

本文档持续更新中，如有新问题请及时反馈。

最后更新：2024年1月