jiebanke/docs/常见问题.md

# 常见问题 (FAQ)

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

## 📋 目录

- [环境搭建问题](#环境搭建问题)
- [开发相关问题](#开发相关问题)
- [部署相关问题](#部署相关问题)
- [数据库问题](#数据库问题)
- [API接口问题](#api接口问题)
- [前端问题](#前端问题)
- [小程序问题](#小程序问题)
- [性能优化问题](#性能优化问题)

## 🛠️ 环境搭建问题

### Q: Node.js版本要求是什么？
**A:** 项目要求 Node.js 16.x 或更高版本。推荐使用 Node.js 18.x LTS 版本。

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

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

### Q: 安装依赖时出现权限错误怎么办？
**A:** 避免使用 `sudo` 安装npm包，建议配置npm全局目录：

```bash
# 创建全局目录
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服务运行**
   ```bash
   # macOS
   brew services start mysql
   
   # Linux
   sudo systemctl start mysql
   
   # Windows
   net start mysql
   ```

2. **检查连接配置**
   ```javascript
   // backend/.env
   DB_HOST=localhost
   DB_PORT=3306
   DB_NAME=jiebanke
   DB_USER=root
   DB_PASSWORD=your_password
   ```

3. **创建数据库**
   ```sql
   CREATE DATABASE jiebanke CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   ```

### Q: Redis连接问题如何解决？
**A:** 确保Redis服务正常运行：

```bash
# 启动Redis服务
redis-server

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

## 💻 开发相关问题

### Q: 如何重置数据库？
**A:** 使用项目提供的重置脚本：

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

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

### Q: 热重载不工作怎么办？
**A:** 检查以下配置：

1. **后端热重载**
   ```bash
   # 确保使用nodemon
   npm run dev
   
   # 检查nodemon配置
   cat nodemon.json
   ```

2. **前端热重载**
   ```bash
   # 确保Vite配置正确
   npm run dev
   
   # 检查vite.config.ts中的server配置
   ```

### Q: ESLint报错如何解决？
**A:** 常见解决方案：

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

# 检查ESLint配置
cat .eslintrc.js

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

### Q: 如何调试API接口？
**A:** 推荐使用以下工具：

1. **使用内置测试脚本**
   ```bash
   cd backend
   npm run test:api
   ```

2. **使用Postman或Insomnia**
   - 导入API文档中的接口定义
   - 配置环境变量

3. **使用curl命令**
   ```bash
   # 测试登录接口
   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版本**
   ```bash
   docker --version
   docker-compose --version
   ```

2. **检查端口占用**
   ```bash
   # 检查端口是否被占用
   lsof -i :3000
   lsof -i :8080
   ```

3. **查看容器日志**
   ```bash
   docker-compose logs backend
   docker-compose logs admin-system
   ```

### Q: Nginx配置问题如何解决？
**A:** 常见配置问题：

1. **检查配置文件语法**
   ```bash
   nginx -t
   ```

2. **重新加载配置**
   ```bash
   nginx -s reload
   ```

3. **查看错误日志**
   ```bash
   tail -f /var/log/nginx/error.log
   ```

### Q: SSL证书配置问题？
**A:** 使用Let's Encrypt免费证书：

```bash
# 安装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. **检查迁移文件**
   ```bash
   # 查看迁移状态
   npx sequelize-cli db:migrate:status
   
   # 回滚迁移
   npx sequelize-cli db:migrate:undo
   ```

2. **手动执行SQL**
   ```sql
   -- 查看表结构
   DESCRIBE users;
   
   -- 检查约束
   SHOW CREATE TABLE users;
   ```

### Q: 数据库性能问题如何优化？
**A:** 常见优化方案：

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

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

3. **配置优化**
   ```ini
   # my.cnf
   [mysqld]
   innodb_buffer_pool_size = 1G
   query_cache_size = 256M
   ```

## 🔌 API接口问题

### Q: 接口返回401未授权错误？
**A:** 检查JWT token配置：

1. **确认token格式**
   ```javascript
   // 请求头格式
   Authorization: Bearer <your-jwt-token>
   ```

2. **检查token有效期**
   ```javascript
   // 解码token查看过期时间
   const jwt = require('jsonwebtoken');
   const decoded = jwt.decode(token);
   console.log(decoded.exp);
   ```

### Q: 跨域问题如何解决？
**A:** 配置CORS中间件：

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

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

### Q: 文件上传失败怎么办？
**A:** 检查以下配置：

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

2. **存储路径权限**
   ```bash
   # 确保上传目录有写权限
   chmod 755 uploads/
   ```

## 🎨 前端问题

### Q: 组件样式不生效怎么办？
**A:** 检查以下几个方面：

1. **CSS作用域**
   ```vue
   <style scoped>
   /* 组件内样式 */
   </style>
   
   <style>
   /* 全局样式 */
   </style>
   ```

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

### Q: 路由跳转问题？
**A:** 常见解决方案：

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

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

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

### Q: 状态管理问题？
**A:** 使用Pinia进行状态管理：

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

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

## 📱 小程序问题

### Q: 小程序真机调试问题？
**A:** 常见解决方案：

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

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

### Q: 小程序分包加载问题？
**A:** 配置分包策略：

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

## ⚡ 性能优化问题

### Q: 页面加载慢怎么优化？
**A:** 常见优化策略：

1. **代码分割**
   ```javascript
   // 路由懒加载
   const UserProfile = () => import('./components/UserProfile.vue');
   ```

2. **图片优化**
   ```html
   <!-- 使用WebP格式 -->
   <img src="image.webp" alt="description" loading="lazy">
   ```

3. **缓存策略**
   ```javascript
   // 设置HTTP缓存
   app.use(express.static('public', {
     maxAge: '1d'
   }));
   ```

### Q: 数据库查询慢如何优化？
**A:** 优化建议：

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

## 📞 获取帮助

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

### 技术支持
- **GitHub Issues**: [提交问题](https://github.com/jiebanke/jiebanke/issues)
- **开发者邮箱**: dev@jiebanke.com
- **技术QQ群**: 123456789

### 文档资源
- **开发指南**: [docs/开发指南.md](开发指南.md)
- **API文档**: [docs/API接口文档.md](API接口文档.md)
- **部署指南**: [docs/部署指南.md](部署指南.md)

### 社区资源
- **官方论坛**: https://forum.jiebanke.com
- **技术博客**: https://blog.jiebanke.com
- **视频教程**: https://video.jiebanke.com

---

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

*最后更新：2024年1月*