# 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 - 清理缓存，焕然一新！* ✨🔧