Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,429 @@
+# MeshRay - 缓存清理指南
+
+**更新时间**: 2026-03-24  
+**适用场景**: 前端修改后未生效、MIME 类型错误、页面显示异常
+
+---
+
+## 🎯 **需要清理的缓存类型**
+
+### 1️⃣ **Go 编译缓存** ⭐⭐⭐
+
+**命令**:
+```bash
+go clean -cache
+```
+
+**作用**: 
+- 清理 Go 编译器的构建缓存
+- 确保重新编译所有包
+- 解决 IDE 标红但编译通过的奇怪问题
+
+**何时使用**:
+- ✅ 修改了 embed.go 或静态资源
+- ✅ 修改了后端代码
+- ✅ 遇到奇怪的编译错误
+- ✅ IDE 提示与编译结果不一致
+
+---
+
+### 2️⃣ **前端 Vite 构建缓存** ⭐⭐
+
+**清理方法**:
+
+#### 方法 A: 删除 node_modules/.vite
+```bash
+cd web
+Remove-Item -Recurse -Force "node_modules/.vite"
+npm run build
+```
+
+#### 方法 B: 强制重新编译
+```bash
+cd web
+npm run build -- --force
+```
+
+**作用**:
+- 清理 Vite 的预构建依赖
+- 解决模块解析错误
+- 强制重新分析依赖
+
+**何时使用**:
+- ✅ 安装了新的 npm 包
+- ✅ 修改了 vite.config.js
+- ✅ 遇到 import 错误
+- ✅ 编译产物异常
+
+---
+
+### 3️⃣ **浏览器缓存** ⭐⭐⭐
+
+#### Chrome/Edge 浏览器：
+
+**方法 A: 硬性重新加载（推荐）**
+1. 打开开发者工具 `F12`
+2. **右键点击**刷新按钮🔄
+3. 选择 **"清空缓存并硬性重新加载"**
+
+**方法 B: 禁用缓存（开发环境必备）**
+1. 按 `F12` 打开开发者工具
+2. 进入 **Network** 标签
+3. ✅ 勾选 **"Disable cache"**
+
+**方法 C: 完全清除**
+1. 按 `Ctrl + Shift + Delete`
+2. 时间范围：**时间不限**
+3. 勾选：
+   - ✅ 浏览历史记录
+   - ✅ Cookie 及其他网站数据
+   - ✅ 缓存的图片和文件
+4. 点击 **"清除数据"**
+
+---
+
+#### Firefox 浏览器：
+
+**方法 A: 硬性重新加载**
+- `Ctrl + F5` 或 `Ctrl + Shift + R`
+
+**方法 B: 清除所有缓存**
+1. 按 `Ctrl + Shift + Delete`
+2. 时间范围：**全部**
+3. 勾选：**缓存**
+4. 点击 **"确定"**
+
+---
+
+### 4️⃣ **dist 目录清理** ⭐⭐
+
+**场景**: 需要彻底清理前端编译产物
+
+**命令**:
+```bash
+cd web
+Remove-Item -Recurse -Force "dist/*"
+npm run build
+```
+
+**作用**:
+- 清空旧的编译产物
+- 确保生成最新的文件
+- 避免文件残留导致的问题
+
+**何时使用**:
+- ✅ 删除了某些 Vue 组件
+- ✅ 重构了目录结构
+- ✅ 怀疑编译产物有问题
+
+---
+
+## 🔄 **完整的清理流程**
+
+### 标准流程（推荐）⭐⭐⭐
+
+```bash
+# 1. 停止服务
+Get-Process -Name "meshray*" -ErrorAction SilentlyContinue | Stop-Process -Force
+
+# 2. 清理 Go 缓存
+go clean -cache
+
+# 3. 清理前端缓存（可选）
+cd web
+Remove-Item -Recurse -Force "node_modules/.vite"
+
+# 4. 重新编译前端
+npm run build
+
+# 5. 重新创建 embed.go（重要！）
+cat > dist/embed.go << 'EOF'
+package dist
+
+import "embed"
+
+//go:embed *
+var WebAssets embed.FS
+EOF
+
+# 6. 返回项目根目录
+cd ..
+
+# 7. 重新编译后端
+go build -o meshray.exe -ldflags "-s -w -H=windowsgui" ./cmd/meshray
+
+# 8. 启动服务
+.\meshray.exe
+
+# 9. 测试访问
+curl.exe http://localhost:9531/
+```
+
+---
+
+### 快速流程（日常开发）⭐⭐
+
+```bash
+# 1. 清理 Go 缓存
+go clean -cache
+
+# 2. 重新编译前端
+cd web; npm run build; cd ..
+
+# 3. 重新创建 embed.go
+echo "package dist`n`nimport `"embed`"`n`n//go:embed *`nvar WebAssets embed.FS" > web\dist\embed.go
+
+# 4. 重新编译后端
+go build -o meshray.exe -ldflags "-s -w -H=windowsgui" ./cmd/meshray
+
+# 5. 重启服务
+Get-Process meshray* | Stop-Process -Force; .\meshray.exe
+```
+
+---
+
+## 🛠️ **PowerShell 一键清理脚本**
+
+创建文件：`clean_and_build.ps1`
+
+```powershell
+# MeshRay 清理并重建脚本
+
+Write-Host "🧹 开始清理..." -ForegroundColor Cyan
+
+# 1. 停止服务
+Write-Host "`n📴 停止 MeshRay 服务..." -ForegroundColor Yellow
+Get-Process -Name "meshray*" -ErrorAction SilentlyContinue | Stop-Process -Force
+Start-Sleep -Seconds 2
+
+# 2. 清理 Go 缓存
+Write-Host "`n🗑️ 清理 Go 编译缓存..." -ForegroundColor Yellow
+go clean -cache
+
+# 3. 清理前端缓存
+Write-Host "`n🗑️ 清理 Vite 缓存..." -ForegroundColor Yellow
+if (Test-Path "web\node_modules\.vite") {
+    Remove-Item -Recurse -Force "web\node_modules\.vite"
+}
+
+# 4. 清理 dist 目录（可选）
+# Write-Host "`n🗑️ 清理 dist 目录..." -ForegroundColor Yellow
+# Remove-Item -Recurse -Force "web\dist\*"
+
+# 5. 重新编译前端
+Write-Host "`n🔨 编译前端..." -ForegroundColor Yellow
+Set-Location web
+npm run build
+Set-Location ..
+
+# 6. 重新创建 embed.go
+Write-Host "`n📝 创建 embed.go..." -ForegroundColor Yellow
+@"
+package dist
+
+import "embed"
+
+//go:embed *
+var WebAssets embed.FS
+"@ | Out-File -FilePath "web\dist\embed.go" -Encoding utf8 -NoNewline
+
+# 7. 重新编译后端
+Write-Host "`n🔨 编译后端..." -ForegroundColor Yellow
+go build -o meshray.exe -ldflags "-s -w -H=windowsgui" ./cmd/meshray
+
+# 8. 启动服务
+Write-Host "`n🚀 启动 MeshRay..." -ForegroundColor Yellow
+Start-Process ".\meshray.exe"
+
+# 9. 等待启动
+Start-Sleep -Seconds 3
+
+# 10. 测试访问
+Write-Host "`n🧪 测试访问..." -ForegroundColor Yellow
+$response = curl.exe http://localhost:9531/ -s
+if ($response -match "DOCTYPE") {
+    Write-Host "`n✅ 成功！前端页面可访问" -ForegroundColor Green
+} else {
+    Write-Host "`n❌ 失败！请检查日志" -ForegroundColor Red
+}
+
+Write-Host "`n✨ 完成！" -ForegroundColor Green
+Write-Host "`n📱 访问地址：http://localhost:9531" -ForegroundColor Cyan
+```
+
+**使用方法**:
+```bash
+.\clean_and_build.ps1
+```
+
+---
+
+## 📊 **常见问题排查**
+
+### 问题 1: 前端修改后不生效
+
+**排查步骤**:
+```bash
+# 1. 检查 dist 目录是否更新
+ls web\dist\index.html | Select-Object LastWriteTime
+
+# 2. 清理浏览器缓存
+# F12 → Network → Disable cache
+
+# 3. 硬性重新加载
+# Ctrl + Shift + R
+```
+
+---
+
+### 问题 2: MIME 类型错误
+
+**解决方案**:
+```bash
+# 1. 清理所有缓存
+go clean -cache
+Remove-Item -Recurse -Force "web\dist\*"
+npm run build
+
+# 2. 重新创建 embed.go
+# （见上方脚本）
+
+# 3. 重新编译
+go build
+
+# 4. 浏览器禁用缓存
+# F12 → Network → ✅ Disable cache
+```
+
+---
+
+### 问题 3: embed.go 丢失
+
+**症状**:
+```
+no required module provides package git.zkcoi.com/zkcoi/meshray/web/dist
+```
+
+**解决**:
+```bash
+# 重新创建 embed.go
+@"
+package dist
+
+import "embed"
+
+//go:embed *
+var WebAssets embed.FS
+"@ | Out-File -FilePath "web\dist\embed.go" -Encoding utf8 -NoNewline
+
+# 重新编译
+go build
+```
+
+---
+
+### 问题 4: 浏览器仍然显示旧页面
+
+**强制刷新方法**:
+
+#### Chrome/Edge:
+1. `Ctrl + Shift + Delete`
+2. 时间范围：**时间不限**
+3. 勾选所有选项
+4. 清除数据
+5. **关闭浏览器**
+6. 重新打开
+
+#### 隐私模式测试:
+```bash
+chrome.exe --incognito http://localhost:9531
+msedge.exe --inprivate http://localhost:9531
+```
+
+---
+
+## 📋 **检查清单**
+
+完成以下检查确保缓存已完全清理：
+
+- [x] ✅ `go clean -cache` 执行成功
+- [x] ✅ 前端已重新编译 (`npm run build`)
+- [x] ✅ `web/dist/embed.go` 已重新创建
+- [x] ✅ 后端已重新编译
+- [x] ✅ 服务已重启
+- [x] ✅ 浏览器缓存已禁用（Disable cache）
+- [x] ✅ 硬性重新加载执行（Ctrl+Shift+R）
+- [ ] ⏳ curl 测试返回正确的 HTML
+- [ ] ⏳ 浏览器中页面正常显示
+
+---
+
+## 💡 **最佳实践**
+
+### 开发习惯：
+
+1. **每次修改前端后**:
+   ```bash
+   npm run build
+   # 然后刷新浏览器（禁用缓存）
+   ```
+
+2. **每次修改后端后**:
+   ```bash
+   go clean -cache
+   go build
+   # 然后重启服务
+   ```
+
+3. **遇到奇怪的问题时**:
+   - 先清理所有缓存
+   - 重新编译前后端
+   - 浏览器隐私模式测试
+
+---
+
+### 自动化建议：
+
+**VS Code Tasks**:
+
+创建 `.vscode/tasks.json`:
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Clean and Rebuild",
+      "type": "shell",
+      "command": ".\\clean_and_build.ps1",
+      "group": "build",
+      "presentation": {
+        "reveal": "always",
+        "panel": "new"
+      }
+    }
+  ]
+}
+```
+
+**快捷键**: `Ctrl+Shift+P` → `Tasks: Run Task` → `Clean and Rebuild`
+
+---
+
+## 🎯 **总结**
+
+### 缓存清理优先级：
+
+| 场景 | 优先级 | 操作 |
+|------|--------|------|
+| **前端修改** | ⭐⭐ | `npm run build` + 浏览器硬刷新 |
+| **后端修改** | ⭐⭐ | `go clean -cache` + 重启服务 |
+| **路由/组件删除** | ⭐⭐⭐ | 清理 dist + 重新编译 + 浏览器清缓存 |
+| **MIME 类型错误** | ⭐⭐⭐ | 全部清理 + 隐私模式测试 |
+| **embed.go 问题** | ⭐⭐⭐ | 重新创建 embed.go + 重新编译 |
+
+---
+
+**状态**: ✅ **缓存已清理，服务已重启**  
+**下一步**: 请在浏览器中访问 http://localhost:9531 并测试  
+
+*MeshRay - 清理缓存，焕然一新！* ✨🔧