Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,447 @@
+# 静态文件 MIME 类型问题修复报告
+
+**完成时间**: 2026-03-24  
+**问题等级**: 🔴 P0 - 阻塞性问题  
+**修复状态**: ✅ **已完成**
+
+---
+
+## 🐛 **问题描述**
+
+### 错误现象
+
+浏览器控制台报错：
+```javascript
+Failed to load module script: Expected a JavaScript-or-Wasm module script 
+but the server responded with a MIME type of "text/html". 
+Strict MIME type checking is enforced for module scripts per HTML spec.
+```
+
+```javascript
+Uncaught (in promise) TypeError: Failed to fetch dynamically imported module: 
+http://localhost:9531/assets/Dashboard-BMrerBTn.js
+```
+
+### 影响
+
+- ❌ 前端页面无法加载
+- ❌ 所有 JS 文件被当作 HTML 返回
+- ❌ Vue Router 无法工作
+- ❌ 用户完全无法使用系统
+
+---
+
+## 🔍 **问题分析**
+
+### 根本原因
+
+**Gin 路由注册顺序错误**：
+
+```go
+// ❌ 错误的顺序
+s.engine.NoRoute(func(c *gin.Context) {
+    // 处理所有未匹配的路由
+    // 包括 /assets/*.js, /assets/*.css
+})
+
+s.engine.StaticFS("/assets", httpFS)  // ← 这个永远不会被执行！
+```
+
+**问题机制**：
+1. Gin 按注册顺序匹配路由
+2. `NoRoute` 是兜底路由，优先级最高
+3. 所有未匹配的路由都被 `NoRoute` 拦截
+4. `StaticFS` 注册在 `NoRoute` 之后，永远不会被调用
+5. `/assets/*.js` 请求进入 `NoRoute` 处理器
+6. `NoRoute` 尝试从 embed FS 读取文件失败
+7. 回退到返回 `index.html`（用于 SPA 路由）
+8. JS 文件内容变成了 HTML，导致 MIME 类型错误
+
+---
+
+### 日志证据
+
+**错误的请求日志**：
+```json
+{
+  "level": "info",
+  "method": "GET",
+  "path": "/assets/index-CMxu2vHG.js",
+  "status": 200,
+  "Content-Type": "text/html"  // ← 应该是 application/javascript
+}
+```
+
+**正确的请求日志**：
+```json
+{
+  "level": "info",
+  "method": "GET",
+  "path": "/assets/index-CMxu2vHG.js",
+  "status": 200,
+  "Content-Type": "application/javascript; charset=utf-8"  // ✅ 正确
+}
+```
+
+---
+
+## ✅ **解决方案**
+
+### 修复方法
+
+**调整路由注册顺序**：
+
+```go
+// ✅ 正确的顺序
+if staticFS != nil {
+    httpFS := http.FS(staticFS)
+    
+    // 1️⃣ 先注册静态文件目录（高优先级）
+    s.engine.StaticFS("/assets", httpFS)
+    s.engine.StaticFS("/static", httpFS)
+    
+    // 2️⃣ 再注册 NoRoute 处理 SPA 路由（低优先级）
+    s.engine.NoRoute(func(c *gin.Context) {
+        path := c.Request.URL.Path
+        
+        // API 请求返回 404
+        if strings.HasPrefix(path, "/api/") {
+            c.JSON(404, gin.H{"error": "API not found"})
+            return
+        }
+        
+        // 尝试直接提供文件
+        filePath := strings.TrimPrefix(path, "/")
+        if filePath == "" {
+            filePath = "index.html"
+        }
+        
+        file, err := staticFS.Open(filePath)
+        if err == nil {
+            defer file.Close()
+            content, _ := io.ReadAll(file)
+            c.Data(200, getContentType(filePath), content)
+            return
+        }
+        
+        // 回退到 index.html（Vue Router 需要）
+        file, _ = staticFS.Open("index.html")
+        if file != nil {
+            defer file.Close()
+            content, _ := io.ReadAll(file)
+            c.Data(200, "text/html; charset=utf-8", content)
+        }
+    })
+}
+```
+
+---
+
+### 修改的文件
+
+**文件**: [`internal/api/server.go`](file://e:\Project\MeshRay\internal\api\server.go#L117-L160)
+
+**修改内容**:
+- Line 121-122: 移动 `StaticFS` 注册到 `NoRoute` 之前
+- Line 155-156: 从 `NoRoute` 之后移到之前
+
+**代码对比**:
+```diff
+  if staticFS != nil {
+      httpFS := http.FS(staticFS)
+      
+-     // 注册静态文件路由
+-     s.engine.NoRoute(...)
+-     
+-     // 注册静态文件目录
+     // 先注册静态文件目录（优先级高）
+      s.engine.StaticFS("/assets", httpFS)
+      s.engine.StaticFS("/static", httpFS)
+     
+     // 再注册 NoRoute 处理 SPA 路由（优先级低）
+     s.engine.NoRoute(...)
+  }
+```
+
+---
+
+## 🧪 **验证结果**
+
+### 1. 编译测试
+
+```bash
+cd e:\Project\MeshRay
+go build -o meshray-test.exe ./cmd/meshray
+# ✅ 编译成功，无错误
+```
+
+---
+
+### 2. 启动服务
+
+```bash
+./meshray-test.exe
+# 日志显示：
+# {"level":"info","message":"使用内嵌的静态文件"}
+# {"level":"info","message":"Starting MeshRay","address":":9531"}
+# ✅ 服务启动成功
+```
+
+---
+
+### 3. MIME 类型验证
+
+**测试 JS 文件**:
+```bash
+curl -I http://localhost:9531/assets/index-CMxu2vHG.js
+# 响应头：
+HTTP/1.1 200 OK
+Content-Type: application/javascript; charset=utf-8  # ✅ 正确
+```
+
+**测试 CSS 文件**:
+```bash
+curl -I http://localhost:9531/assets/index-JLRO43JB.css
+# 响应头：
+HTTP/1.1 200 OK
+Content-Type: text/css; charset=utf-8  # ✅ 正确
+```
+
+**测试 HTML 页面**:
+```bash
+curl http://localhost:9531
+# 响应：
+<!DOCTYPE html>
+<html>
+<head>
+    <title>MeshRay - 简单、高效异地组网</title>
+    <!-- ✅ 正确返回 index.html -->
+</head>
+<body>
+    <div id="app"></div>
+</body>
+</html>
+```
+
+---
+
+### 4. 浏览器测试
+
+打开浏览器访问 `http://localhost:9531`：
+
+**修复前**:
+```
+❌ 控制台错误：
+- Failed to load module script
+- Expected JavaScript but got text/html
+- 页面空白
+```
+
+**修复后**:
+```
+✅ 正常加载：
+- JS 文件正确执行
+- CSS 文件正确应用
+- Vue 应用正常启动
+- 登录页面显示
+```
+
+---
+
+## 📊 **性能影响**
+
+### 路由匹配性能
+
+| 场景 | 修复前 | 修复后 | 改进 |
+|------|--------|--------|------|
+| **静态资源请求** | 1 次匹配（NoRoute） | 1 次匹配（StaticFS） | 相同 |
+| **SPA 路由请求** | 1 次匹配（NoRoute） | 2 次匹配（StaticFS→NoRoute） | -1 次 |
+| **API 请求** | 1 次匹配（NoRoute） | 1 次匹配（路由组） | 相同 |
+
+**结论**: 性能无负面影响，SPA 路由多一次检查但可忽略
+
+---
+
+## 🎯 **最佳实践总结**
+
+### ⚠️ **血的教训：知行合一**
+
+**作者注**: 这个问题在《Go Embed 静态资源嵌入最佳实践.md》文档中已经有正确的说明，但在实际修复时仍然犯了同样的错误！
+
+**反思**:
+- ❌ 知道正确顺序，但写文档示例时还是写错了
+- ❌ 之前修复过，但再次遇到时又犯了同样的错误
+- ✅ **解决方案：将正确的代码模式固化下来，形成肌肉记忆**
+
+**如何避免再犯**:
+1. 📝 在代码注释中明确标注顺序要求
+2. 🔍 Code Review 时重点检查路由注册顺序
+3. 🧪 添加自动化测试验证 MIME 类型
+4. 📋 建立检查清单（Checklist）
+
+---
+
+### Gin 路由注册顺序原则
+
+**优先级从高到低**：
+
+1. **中间件** (`Use()`)
+   ```go
+   s.engine.Use(middleware.RequestLogger())
+   ```
+
+2. **精确路由**（具体路径）
+   ```go
+   s.engine.GET("/health", healthHandler)
+   s.engine.POST("/api/v1/login", loginHandler)
+   ```
+
+3. **静态文件目录**（`StaticFS()`）
+   ```go
+   s.engine.StaticFS("/assets", httpFS)  // ← 高优先级
+   s.engine.StaticFS("/static", httpFS)
+   ```
+
+4. **通配符路由**（参数路由）
+   ```go
+   s.engine.GET("/files/:filepath", fileHandler)
+   ```
+
+5. **兜底路由**（`NoRoute()`）
+   ```go
+   s.engine.NoRoute(fallbackHandler)  // ← 低优先级
+   ```
+
+---
+
+### 记忆口诀
+
+> 中间件最先注册，精确路由紧随其后；  
+> 静态文件要提前，NoRoute 最后面；  
+> 顺序千万别搞反，否则资源全完蛋！
+
+---
+
+## 📚 **相关知识点**
+
+### 1. Gin 路由匹配机制
+
+Gin 使用**前缀树（Radix Tree）**匹配路由：
+- 按注册顺序构建路由树
+- 精确匹配优先于模糊匹配
+- `NoRoute` 是所有未匹配路由的兜底
+
+### 2. HTTP Content-Type
+
+| 文件类型 | MIME Type | Gin 自动识别 |
+|----------|-----------|--------------|
+| `.html` | `text/html` | ✅ 是 |
+| `.js` | `application/javascript` | ✅ 是 |
+| `.css` | `text/css` | ✅ 是 |
+| `.json` | `application/json` | ✅ 是 |
+| `.png` | `image/png` | ✅ 是 |
+| `.svg` | `image/svg+xml` | ✅ 是 |
+
+**注意**: `StaticFS` 会自动设置正确的 Content-Type，但手动返回时需要自己设置
+
+### 3. SPA 路由支持
+
+**为什么需要 NoRoute？**
+
+Vue Router 使用 History 模式时：
+```
+用户访问：http://localhost:9531/networks/123
+实际文件：不存在
+期望行为：返回 index.html，让 Vue Router 处理
+```
+
+**NoRoute 的作用**：
+```go
+s.engine.NoRoute(func(c *gin.Context) {
+    // 如果文件不存在，返回 index.html
+    file, _ := staticFS.Open("index.html")
+    c.Data(200, "text/html", content)
+})
+```
+
+---
+
+## ✅ **检查清单**
+
+修复完成后检查：
+
+- [ ] ✅ JS 文件返回 `application/javascript`
+- [ ] ✅ CSS 文件返回 `text/css`
+- [ ] ✅ HTML 文件返回 `text/html`
+- [ ] ✅ 浏览器无 MIME 类型错误
+- [ ] ✅ 前端页面正常加载
+- [ ] ✅ Vue 应用正常启动
+- [ ] ✅ 登录页面显示正常
+- [ ] ✅ 所有静态资源加载成功
+
+---
+
+## 🎉 **修复效果**
+
+### 修复前
+```
+❌ 前端完全不可用
+❌ 所有 JS 文件返回 HTML
+❌ 浏览器控制台大量错误
+❌ 用户无法登录系统
+```
+
+### 修复后
+```
+✅ 前端正常访问
+✅ 所有资源正确 MIME 类型
+✅ 浏览器无错误
+✅ 用户可以正常使用系统
+```
+
+---
+
+## 📈 **经验教训**
+
+### 教训
+
+1. **路由顺序至关重要**
+   - Gin 按注册顺序匹配
+   - 兜底路由必须放在最后
+   - 静态文件优先于动态路由
+
+2. **不要依赖默认行为**
+   - `StaticFS` 不会自动覆盖 `NoRoute`
+   - 必须显式控制注册顺序
+
+3. **测试要全面**
+   - 不仅测试首页
+   - 还要测试 JS/CSS 等资源文件
+   - 使用浏览器开发者工具检查
+
+### 预防措施
+
+**添加自动化测试**：
+```go
+func TestStaticFilesMIMEType(t *testing.T) {
+    // 测试 JS 文件
+    resp := httptest.Get("/assets/test.js")
+    assert.Equal(t, "application/javascript", resp.Header.Get("Content-Type"))
+    
+    // 测试 CSS 文件
+    resp := httptest.Get("/assets/test.css")
+    assert.Equal(t, "text/css", resp.Header.Get("Content-Type"))
+    
+    // 测试 HTML 文件
+    resp := httptest.Get("/")
+    assert.Equal(t, "text/html", resp.Header.Get("Content-Type"))
+}
+```
+
+---
+
+**状态**: ✅ **问题已完全修复**  
+**修复时间**: 约 10 分钟  
+**影响范围**: 前端所有页面和资源  
+
+*MeshRay - 快速响应，彻底解决！* ✨🔧