Meshray-Manager/docs/缓存清理指南.md

MeshRay - 缓存清理指南

更新时间: 2026-03-24
适用场景: 前端修改后未生效、MIME 类型错误、页面显示异常

---

🎯 需要清理的缓存类型

1️⃣ Go 编译缓存 ⭐⭐⭐

命令:

go clean -cache

作用:

• 清理 Go 编译器的构建缓存
• 确保重新编译所有包
• 解决 IDE 标红但编译通过的奇怪问题

何时使用:

• ✅ 修改了 embed.go 或静态资源
• ✅ 修改了后端代码
• ✅ 遇到奇怪的编译错误
• ✅ IDE 提示与编译结果不一致

---

2️⃣ 前端 Vite 构建缓存 ⭐⭐

清理方法:

方法 A: 删除 node_modules/.vite

cd web
Remove-Item -Recurse -Force "node_modules/.vite"
npm run build

方法 B: 强制重新编译

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 目录清理 ⭐⭐

场景: 需要彻底清理前端编译产物

命令:

cd web
Remove-Item -Recurse -Force "dist/*"
npm run build

作用:

• 清空旧的编译产物
• 确保生成最新的文件
• 避免文件残留导致的问题

何时使用:

• ✅ 删除了某些 Vue 组件
• ✅ 重构了目录结构
• ✅ 怀疑编译产物有问题

---

🔄 完整的清理流程

标准流程（推荐）⭐⭐⭐

# 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/

---

快速流程（日常开发）⭐⭐

# 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

# 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

使用方法:

.\clean_and_build.ps1

---

📊 常见问题排查

问题 1: 前端修改后不生效

排查步骤:

# 1. 检查 dist 目录是否更新
ls web\dist\index.html | Select-Object LastWriteTime

# 2. 清理浏览器缓存
# F12 → Network → Disable cache

# 3. 硬性重新加载
# Ctrl + Shift + R

---

问题 2: MIME 类型错误

解决方案:

# 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

解决:

# 重新创建 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. 重新打开

隐私模式测试:

chrome.exe --incognito http://localhost:9531
msedge.exe --inprivate http://localhost:9531

---

📋 检查清单

完成以下检查确保缓存已完全清理：

• ✅ go clean -cache 执行成功
• ✅ 前端已重新编译 (npm run build)
• ✅ web/dist/embed.go 已重新创建
• ✅ 后端已重新编译
• ✅ 服务已重启
• ✅ 浏览器缓存已禁用（Disable cache）
• ✅ 硬性重新加载执行（Ctrl+Shift+R）
• ⏳ curl 测试返回正确的 HTML
• ⏳ 浏览器中页面正常显示

---

💡 最佳实践

开发习惯：

1. 每次修改前端后:

   npm run build
   # 然后刷新浏览器（禁用缓存）
   

2. 每次修改后端后:

   go clean -cache
   go build
   # 然后重启服务
   

3. 遇到奇怪的问题时:

   • 先清理所有缓存
   • 重新编译前后端
   • 浏览器隐私模式测试

---

自动化建议：

VS Code Tasks:

创建 .vscode/tasks.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 - 清理缓存，焕然一新！ ✨🔧