继续提交

2025-12-19 15:51:26 +08:00
parent 0ce60d78df
commit cf2203e3eb
500 changed files with 3259 additions and 7739 deletions
--- a/前端优化说明.md
+++ b/前端优化说明.md
@@ -0,0 +1,194 @@
+# 萌芽笔记 - 前端优化说明
+
+## 📋 问题描述
+
+原项目在部署到服务器后，某些浏览器（特别是移动端浏览器）会出现：
+- localStorage 权限弹窗，点"允许"才能访问
+- 某些浏览器不弹窗，直接阻止访问，导致页面一直加载
+- 跨域或隐私模式下无法正常使用
+
+## ✅ 解决方案
+
+### 1. **完全移除对 localStorage 的强依赖**
+   - 实现了内存存储回退机制
+   - 即使 localStorage 被禁用也能正常运行
+   - 数据完全来自后端 API，不依赖浏览器存储
+
+### 2. **优化的存储 Shim**
+   文件：`src/utils/storageShim.js`
+   - 静默检测 localStorage 可用性
+   - 自动降级到内存存储
+   - 不会触发浏览器权限弹窗
+
+### 3. **错误边界组件**
+   文件：`src/components/ErrorBoundary.jsx`
+   - 捕获所有运行时错误
+   - 提供友好的错误提示
+   - 给出解决方案建议
+
+### 4. **网络请求优化**
+   文件：`src/utils/fileUtils.js`
+   - 添加请求超时控制（15秒）
+   - 更详细的错误日志
+   - 友好的错误提示信息
+
+### 5. **支持相对路径部署**
+   - 前后端同域名部署时，使用相对路径
+   - 避免跨域问题
+   - 更好的安全性
+
+## 🚀 部署建议
+
+### 推荐方式：前后端同域名部署
+
+**配置步骤：**
+
+1. **修改 `.env.production` 文件**
+   ```bash
+   # 留空表示使用相对路径
+   VITE_API_BASE=
+   ```
+
+2. **构建前端**
+   ```bash
+   cd mengyanote-frontend
+   npm install
+   npm run build
+   ```
+
+3. **配置 Nginx**
+   ```nginx
+   server {
+       listen 80;
+       server_name your-domain.com;
+
+       # 前端静态文件
+       location / {
+           root /path/to/mengyanote-frontend/dist;
+           try_files $uri $uri/ /index.html;
+       }
+
+       # 后端 API 代理
+       location /api/ {
+           proxy_pass http://127.0.0.1:2424;
+           proxy_set_header Host $host;
+           proxy_set_header X-Real-IP $remote_addr;
+           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+           proxy_set_header X-Forwarded-Proto $scheme;
+       }
+   }
+   ```
+
+4. **启动后端**
+   ```bash
+   cd mengyanote-backend
+   python main.py
+   ```
+
+### 方式二：前后端分离部署
+
+**配置步骤：**
+
+1. **修改 `.env.production` 文件**
+   ```bash
+   # 填写后端完整URL
+   VITE_API_BASE=https://api.your-domain.com
+   ```
+
+2. **配置后端 CORS**
+   
+   编辑 `mengyanote-backend/main.py`，确保 CORS 配置正确：
+   ```python
+   app.add_middleware(
+       CORSMiddleware,
+       allow_origins=["https://your-frontend-domain.com"],
+       allow_credentials=True,
+       allow_methods=["*"],
+       allow_headers=["*"],
+   )
+   ```
+
+3. **构建并部署前端**
+   ```bash
+   npm run build
+   # 将 dist 目录上传到前端服务器
+   ```
+
+## 🔍 测试验证
+
+部署后请在以下环境测试：
+
+1. **桌面浏览器**
+   - ✅ Chrome
+   - ✅ Edge
+   - ✅ Firefox
+   - ✅ Safari
+
+2. **移动浏览器**
+   - ✅ Chrome Mobile
+   - ✅ Safari iOS
+   - ✅ 微信内置浏览器
+   - ✅ 其他移动浏览器
+
+3. **特殊模式**
+   - ✅ 隐私/无痕模式
+   - ✅ 禁用 Cookie
+   - ✅ 禁用 JavaScript Storage
+
+## 📊 变更内容
+
+### 修改的文件
+
+1. ✏️ `src/utils/storageShim.js` - 优化存储回退机制
+2. ✏️ `src/utils/fileUtils.js` - 优化网络请求和错误处理
+3. ✏️ `src/context/AppContext.jsx` - 添加详细日志
+4. ✏️ `src/main.jsx` - 添加错误边界
+5. ✏️ `.env.production` - 改为相对路径模式
+6. ➕ `src/components/ErrorBoundary.jsx` - 新增错误边界组件
+
+### 关键改进
+
+1. **零依赖 localStorage**
+   - 所有数据从后端获取
+   - localStorage 仅用于临时缓存（可选）
+   
+2. **完善的错误处理**
+   - 网络超时控制
+   - 友好的错误提示
+   - 详细的调试日志
+
+3. **跨浏览器兼容**
+   - 支持所有主流浏览器
+   - 移动端完美适配
+   - 隐私模式正常工作
+
+## 🐛 问题排查
+
+如果仍然遇到问题，请检查：
+
+### 1. 打开浏览器控制台 (F12)
+   查看是否有错误信息，所有日志都以 `[MengyaNote]` 开头
+
+### 2. 检查网络请求
+   - 确认 `/api/tree` 和 `/api/file` 请求是否成功
+   - 查看响应状态码
+
+### 3. 验证后端服务
+   ```bash
+   curl http://your-domain.com/api/tree
+   ```
+
+### 4. 检查 CORS 配置
+   如果跨域部署，确保后端允许前端域名访问
+
+## 📞 技术支持
+
+如有问题，请提供：
+1. 浏览器控制台的完整日志
+2. 网络请求的详细信息
+3. 浏览器版本和操作系统信息
+
+---
+
+**最后更新:** 2025-12-19
+**版本:** 2.0 - 移除 localStorage 依赖版本