由于本次代码变更内容为空，无法生成有效的提交信息

2025-09-20 10:54:40 +08:00
parent 62d122cff6
commit 68a96b7e82
7 changed files with 1085 additions and 27 deletions
--- a/docs/常见问题.md
+++ b/docs/常见问题.md
@@ -0,0 +1,469 @@
+# 常见问题 (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月*