Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,337 @@
+# MeshRay - MIME 类型错误快速解决指南
+
+**最后更新**: 2026-03-24  
+**问题**: `Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/html"`
+
+---
+
+## 🎯 **问题诊断**
+
+### 当前状态检查
+
+```bash
+# 测试后端实际返回
+curl.exe http://localhost:9531/assets/Dashboard-BMrerBTn.js -I
+
+# 预期结果：
+HTTP/1.1 200 OK
+Content-Type: application/javascript; charset=utf-8  ✅
+```
+
+**如果看到上面的结果，说明后端已修复，问题是浏览器缓存！**
+
+---
+
+## ✅ **解决方案（按顺序执行）**
+
+### 方案 1: 硬性重新加载（推荐）⭐
+
+#### Chrome/Edge 浏览器：
+
+1. **打开开发者工具**: 按 `F12`
+2. **右键点击刷新按钮** 🔄
+3. **选择**: "清空缓存并硬性重新加载"
+
+![Hard Reload](https://i.imgur.com/xyz.png)
+
+---
+
+### 方案 2: 禁用缓存（开发环境必备）⭐⭐⭐
+
+#### 步骤：
+
+1. **打开开发者工具**: `F12`
+2. **进入 Network 标签**
+3. **勾选**: ✅ `Disable cache`
+
+**效果**: 
+- ✅ 每次访问都从服务器重新加载
+- ✅ 不会使用任何缓存
+- ✅ 开发调试必备
+
+---
+
+### 方案 3: 清除所有缓存数据
+
+#### Chrome/Edge:
+
+1. 按 `Ctrl + Shift + Delete`
+2. 时间范围：**时间不限**
+3. 勾选：
+   - ✅ 浏览历史记录
+   - ✅ Cookie 及其他网站数据
+   - ✅ 缓存的图片和文件
+4. 点击 **"清除数据"**
+
+---
+
+### 方案 4: 使用隐私模式
+
+#### 快捷键：
+
+- **Chrome**: `Ctrl + Shift + N`
+- **Edge**: `Ctrl + Shift + P`
+
+**效果**: 
+- ✅ 不使用任何现有缓存
+- ✅ 不保存新的缓存
+- ✅ 适合测试
+
+---
+
+## 🔍 **验证方法**
+
+### 步骤 1: 打开开发者工具
+
+按 `F12` 打开
+
+---
+
+### 步骤 2: 检查 Network 标签
+
+1. 进入 **Network** 标签
+2. 刷新页面 (`F5`)
+3. 找到 `Dashboard-BMrerBTn.js` 请求
+4. 查看 **Size** 列：
+
+**✅ 正常情况**:
+```
+Size: 15.2 kB (disk cache)  ❌ 使用了缓存
+Size: 15.2 kB               ✅ 从服务器加载
+```
+
+---
+
+### 步骤 3: 检查 Response Headers
+
+点击 `Dashboard-BMrerBTn.js` 请求，查看 **Headers** 标签：
+
+**✅ 正确响应**:
+```http
+HTTP/1.1 200 OK
+Content-Type: application/javascript; charset=utf-8
+```
+
+**❌ 错误响应**:
+```http
+HTTP/1.1 200 OK
+Content-Type: text/html; charset=utf-8
+```
+
+---
+
+### 步骤 4: 检查 Console
+
+进入 **Console** 标签：
+
+**✅ 正常情况**:
+```
+无错误信息
+```
+
+**❌ 仍有问题**:
+```javascript
+Failed to load module script: Expected a JavaScript-or-Wasm module script 
+but the server responded with a MIME type of "text/html".
+```
+
+---
+
+## 🛠️ **终极解决方案**
+
+### 如果以上方法都无效：
+
+#### 步骤 1: 完全关闭浏览器
+
+```bash
+# Windows: 确保所有浏览器进程都关闭
+任务管理器 → 结束所有 Chrome/Edge 进程
+```
+
+---
+
+#### 步骤 2: 删除缓存目录
+
+**Windows**:
+
+```powershell
+# Chrome 缓存
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Google\Chrome\User Data\Default\Cache"
+
+# Edge 缓存
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Microsoft\Edge\User Data\Default\Cache"
+```
+
+**⚠️ 警告**: 这会清除所有浏览器缓存！
+
+---
+
+#### 步骤 3: 重启服务
+
+```bash
+cd e:\Project\MeshRay
+
+# 停止旧服务
+Get-Process -Name "meshray*" -ErrorAction SilentlyContinue | Stop-Process -Force
+
+# 清理编译缓存
+go clean -cache
+
+# 重新编译
+go build -o meshray.exe -ldflags "-s -w -H=windowsgui" ./cmd/meshray
+
+# 启动新服务
+.\meshray.exe
+```
+
+---
+
+#### 步骤 4: 重新启动浏览器
+
+打开浏览器，访问 http://localhost:9531
+
+---
+
+## 📊 **问题排查流程图**
+
+```mermaid
+graph TD
+    A[看到 MIME 类型错误] --> B{测试后端 API}
+    B -->|返回 text/html| C[❌ 后端路由顺序错误]
+    B -->|返回 application/javascript| D{检查浏览器缓存}
+    C --> E[修改 server.go 路由顺序]
+    E --> F[重新编译并重启服务]
+    F --> G[测试]
+    D -->|有缓存 | H[清除缓存]
+    D -->|无缓存 | I[检查其他问题]
+    H --> J[硬性重新加载]
+    J --> K{问题解决？}
+    K -->|否 | L[禁用缓存]
+    K -->|是 | M[✅ 成功]
+    L --> N[使用隐私模式]
+    N --> O[删除缓存目录]
+    O --> P[重启服务]
+```
+
+---
+
+## 🎯 **预防措施**
+
+### 开发环境配置
+
+#### 1. 始终禁用缓存
+
+**开发者工具 → Network → Disable cache** ✅
+
+---
+
+#### 2. 添加版本号
+
+在前端 `index.html` 中添加版本参数：
+
+```html
+<script type="module" src="/assets/index.js?v=20260324"></script>
+<link rel="stylesheet" href="/assets/style.css?v=20260324">
+```
+
+**效果**: 每次修改后强制浏览器重新加载
+
+---
+
+#### 3. 配置 Vite 开发服务器
+
+`vite.config.js`:
+
+```javascript
+export default defineConfig({
+  server: {
+    headers: {
+      'Cache-Control': 'no-cache, no-store, must-revalidate'
+    }
+  },
+  build: {
+    rollupOptions: {
+      output: {
+        // 添加 hash 到文件名
+        entryFileNames: `assets/[name]-[hash].js`,
+        chunkFileNames: `assets/[name]-[hash].js`,
+        assetFileNames: `assets/[name]-[hash].[ext]`
+      }
+    }
+  }
+})
+```
+
+---
+
+## 📝 **检查清单**
+
+完成以下检查确保问题解决：
+
+- [ ] ✅ curl 测试返回 `application/javascript`
+- [ ] ✅ 开发者工具 Network 中 Disable cache 已勾选
+- [ ] ✅ 硬性重新加载执行成功
+- [ ] ✅ Console 中无 MIME 类型错误
+- [ ] ✅ 前端页面正常加载
+- [ ] ✅ Vue 应用正常启动
+- [ ] ✅ 所有 JS 文件正确加载
+
+---
+
+## 🎉 **成功案例**
+
+### 正确的表现：
+
+**Network 标签**:
+```
+Dashboard-BMrerBTn.js    js        15.2 kB   200 OK    application/javascript
+```
+
+**Console 标签**:
+```
+（无错误信息）
+```
+
+**页面显示**:
+```
+✅ Dashboard 统计卡片正常显示
+✅ Network 列表数据完整
+✅ 所有组件正常渲染
+```
+
+---
+
+## 📚 **相关文档**
+
+- [字段命名修复验证报告.md](./字段命名修复验证报告.md) - DTO 字段修复
+- [静态文件 MIME 类型问题修复.md](./静态文件 MIME 类型问题修复.md) - 后端路由修复
+- [Go Embed 静态资源嵌入最佳实践.md](./Go Embed 静态资源嵌入最佳实践.md) - embed 配置
+
+---
+
+## 💡 **快速命令参考**
+
+### 测试后端：
+```bash
+curl.exe http://localhost:9531/assets/Dashboard-BMrerBTn.js -I
+```
+
+### 重启服务：
+```bash
+Get-Process meshray* | Stop-Process -Force
+go build -o meshray.exe -ldflags "-s -w -H=windowsgui" ./cmd/meshray
+.\meshray.exe
+```
+
+### 清除缓存（PowerShell）：
+```powershell
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Google\Chrome\User Data\Default\Cache"
+```
+
+---
+
+**状态**: ✅ **后端已修复，请清除浏览器缓存**  
+**根本原因**: 浏览器缓存了旧的路由响应（HTML）  
+**解决方法**: 清除缓存或禁用缓存  
+
+*MeshRay - 坚持不懈，直到完美！* ✨🔧