From 97096f309ce2085439c164608ce51566ee1c5fa9 Mon Sep 17 00:00:00 2001
From: weizwz <1124725517@qq.com>
Date: Wed, 19 Nov 2025 11:09:48 +0800
Subject: [PATCH 1/2] =?UTF-8?q?=E4=BC=98=E5=8C=96=E7=95=8C=E9=9D=A2?=
 =?UTF-8?q?=E5=B8=83=E5=B1=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .env.example                              |  6 +++
 README.md                                 |  8 ++++
 app/globals.css                           | 37 +++++++++++++++
 app/layout.tsx                            |  1 +
 app/page.tsx                              | 25 ++++++----
 components/navigation/CategorySidebar.tsx | 58 ++++++++++++-----------
 6 files changed, 97 insertions(+), 38 deletions(-)
 create mode 100644 .env.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..14cd765
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,6 @@
+# 网站 URL（用于生成 Open Graph 和 Twitter 卡片）
+# 开发环境
+# NEXT_PUBLIC_SITE_URL=http://localhost:3000
+
+# 生产环境
+NEXT_PUBLIC_SITE_URL=https://nav.weizwz.com
diff --git a/README.md b/README.md
index 2fc0c2c..481b5b0 100644
--- a/README.md
+++ b/README.md
@@ -42,9 +42,17 @@ Next.js 15 · TypeScript 5 · Tailwind CSS 4 · Ant Design 5 · Redux Toolkit ·
 ## 🚀 快速开始
 
 ```bash
+# 克隆项目
+git clone <repository-url>
+cd frontend-navigation-site
+
 # 安装依赖
 pnpm install
 
+# 配置环境变量（可选）
+cp .env.example .env.local
+# 编辑 .env.local 设置你的网站 URL
+
 # 启动开发服务器
 pnpm dev
 
diff --git a/app/globals.css b/app/globals.css
index d8d2673..00b37cc 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -397,3 +397,40 @@ select:focus-visible {
 .install-success {
   animation: success-bounce 0.5s ease-in-out;
 }
+
+/* 固定布局样式 */
+.h-screen {
+  height: 100vh;
+  height: 100dvh; /* 动态视口高度，移动端更准确 */
+}
+
+/* 确保 body 和 html 不会滚动 */
+html, body {
+  overflow: hidden;
+  height: 100%;
+}
+
+/* 只允许内容区域滚动 */
+#main-content {
+  scroll-behavior: smooth;
+}
+
+/* 优化滚动性能 */
+#main-content {
+  -webkit-overflow-scrolling: touch; /* iOS 平滑滚动 */
+  overscroll-behavior: contain; /* 防止滚动链 */
+}
+
+/* 侧边栏滚动优化 */
+aside {
+  -webkit-overflow-scrolling: touch;
+  overscroll-behavior: contain;
+}
+
+/* 移动端优化 */
+@media (max-width: 1023px) {
+  /* 移动端允许整体滚动 */
+  html, body {
+    overflow: auto;
+  }
+}
diff --git a/app/layout.tsx b/app/layout.tsx
index 7746747..ef2b603 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -5,6 +5,7 @@ import RegisterServiceWorker from './register-sw';
 import '@ant-design/v5-patch-for-react-19';
 
 export const metadata: Metadata = {
+  metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL || 'https://nav.weizwz.com'),
   title: {
     default: '唯知导航',
     template: '%s | 唯知导航',
diff --git a/app/page.tsx b/app/page.tsx
index a348ee4..6a7d883 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -146,19 +146,21 @@ export default function Home() {
   );
 
   return (
-    <div className="min-h-screen flex flex-col bg-gray-50 dark:bg-(--background) transition-theme">
-      {/* 页头组件 */}
-      <Header onMenuClick={() => setDrawerOpen(true)} />
+    <div className="h-screen flex flex-col bg-gray-50 dark:bg-(--background) transition-theme overflow-hidden">
+      {/* 固定顶部 Header */}
+      <div className="flex-none">
+        <Header onMenuClick={() => setDrawerOpen(true)} />
+      </div>
       
-      {/* 主内容区域 */}
-      <div className="flex-1 flex overflow-hidden relative">
+      {/* 主内容区域 - 固定高度，内部滚动 */}
+      <div className="flex-1 flex overflow-hidden">
 
-        {/* 左侧分类导航 - Desktop */}
+        {/* 左侧分类导航 - Desktop - 固定，内部滚动 */}
         <aside 
-          className="hidden lg:block w-48 bg-white dark:bg-antd-dark border-r border-gray-200 dark:border-neutral-700 overflow-y-auto transition-theme"
+          className="hidden lg:flex flex-col w-48 bg-white dark:bg-antd-dark border-r border-gray-200 dark:border-neutral-700 transition-theme overflow-hidden"
           aria-label="分类导航侧边栏"
         >
-          <CategorySidebar style={{height: '100%'}} />
+          <CategorySidebar className="h-full" />
         </aside>
 
         {/* 移动端抽屉 - 分类导航 */}
@@ -169,11 +171,14 @@ export default function Home() {
           open={drawerOpen}
           className="lg:hidden"
           width={280}
+          styles={{
+            body: { padding: 0, height: '100%' }
+          }}
         >
-          <CategorySidebar />
+          <CategorySidebar className="h-full" />
         </Drawer>
 
-        {/* 右侧内容区域 */}
+        {/* 右侧内容区域 - 只有这里滚动 */}
         <main 
           id="main-content" 
           className="flex-1 overflow-y-auto overflow-x-hidden"
diff --git a/components/navigation/CategorySidebar.tsx b/components/navigation/CategorySidebar.tsx
index 096dbd3..f943c90 100644
--- a/components/navigation/CategorySidebar.tsx
+++ b/components/navigation/CategorySidebar.tsx
@@ -327,36 +327,38 @@ const CategorySidebarBase: React.FC<CategorySidebarProps> = ({ className, style
       role="navigation"
       aria-label="分类导航"
     >
-      <div className="flex flex-col h-full">
-        {/* 拖拽分类列表 */}
-        <DndContext
-          sensors={sensors}
-          collisionDetection={closestCenter}
-          onDragEnd={handleDragEnd}
-          modifiers={[restrictToSidebar]}
-        >
-          <SortableContext
-            items={sortedCategories.map((cat) => cat.id)}
-            strategy={verticalListSortingStrategy}
+      <div className="flex flex-col h-full overflow-hidden">
+        {/* 拖拽分类列表 - 可滚动区域 */}
+        <div className="flex-1 overflow-y-auto overflow-x-hidden">
+          <DndContext
+            sensors={sensors}
+            collisionDetection={closestCenter}
+            onDragEnd={handleDragEnd}
+            modifiers={[restrictToSidebar]}
           >
-            <div className="flex-1 p-4 space-y-2 overflow-y-auto">
-              {sortedCategories.map((category) => (
-                <DraggableCategoryItem
-                  key={category.id}
-                  category={category}
-                  isSelected={currentCategory === category.name}
-                  onSelect={handleCategoryChange}
-                  onEdit={handleEditCategory}
-                  onDelete={handleDeleteCategory}
-                  renderIcon={renderIcon}
-                />
-              ))}
-            </div>
-          </SortableContext>
-        </DndContext>
+            <SortableContext
+              items={sortedCategories.map((cat) => cat.id)}
+              strategy={verticalListSortingStrategy}
+            >
+              <div className="p-4 space-y-2">
+                {sortedCategories.map((category) => (
+                  <DraggableCategoryItem
+                    key={category.id}
+                    category={category}
+                    isSelected={currentCategory === category.name}
+                    onSelect={handleCategoryChange}
+                    onEdit={handleEditCategory}
+                    onDelete={handleDeleteCategory}
+                    renderIcon={renderIcon}
+                  />
+                ))}
+              </div>
+            </SortableContext>
+          </DndContext>
+        </div>
         
-        {/* 底部按钮区域 */}
-        <div className="p-4 border-t text-sm border-gray-200 dark:border-neutral-700 space-y-2">
+        {/* 底部按钮区域 - 固定在底部 */}
+        <div className="flex-none p-4 border-t text-sm border-gray-200 dark:border-neutral-700 space-y-2 bg-white dark:bg-antd-dark">
           {/* 未分类数据按钮 - 只在有未分类链接时显示 */}
           {uncategorizedCount > 0 && (
             <Button

From f4d9ff36b8d05f8f14fd2dfc6bfc4f38257481e1 Mon Sep 17 00:00:00 2001
From: weizwz <1124725517@qq.com>
Date: Wed, 19 Nov 2025 15:29:13 +0800
Subject: [PATCH 2/2] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=9B=BE=E7=89=87?=
 =?UTF-8?q?=E9=97=AA=E7=83=81=E9=97=AE=E9=A2=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../CACHE_CLEAR_GUIDE.md                      | 263 ++++++++++++++++++
 README.md                                     |   1 +
 components/navigation/LinkCard.tsx            |  18 +-
 public/sw.js                                  |   6 +-
 public/version.json                           |   6 +-
 5 files changed, 284 insertions(+), 10 deletions(-)
 create mode 100644 .kiro/specs/frontend-navigation-site/CACHE_CLEAR_GUIDE.md

diff --git a/.kiro/specs/frontend-navigation-site/CACHE_CLEAR_GUIDE.md b/.kiro/specs/frontend-navigation-site/CACHE_CLEAR_GUIDE.md
new file mode 100644
index 0000000..5e0820a
--- /dev/null
+++ b/.kiro/specs/frontend-navigation-site/CACHE_CLEAR_GUIDE.md
@@ -0,0 +1,263 @@
+# 缓存清除指南
+
+## 问题现象
+
+更新网站后，可能出现以下问题：
+- ❌ CSP 错误：`connect-src 'self'` 阻止请求
+- ❌ 图标加载失败
+- ❌ 功能异常
+- ❌ 样式不更新
+
+## 原因分析
+
+浏览器缓存了旧版本的文件：
+1. **Service Worker 缓存**：缓存了旧的 `_headers` 文件
+2. **浏览器缓存**：缓存了旧的静态资源
+3. **HTTP 缓存**：CDN 或浏览器的 HTTP 缓存
+
+## 解决方案
+
+### 方法 1：使用清除缓存工具（推荐）
+
+访问：`https://nav.weizwz.com/clear-cache.html`
+
+点击"全部清除并刷新"按钮，自动完成所有清理工作。
+
+### 方法 2：手动清除（开发者）
+
+**Chrome/Edge**：
+```
+1. F12 打开开发者工具
+2. Application → Storage → Clear site data
+3. 勾选所有选项
+4. 点击 "Clear site data"
+5. 刷新页面（Ctrl+Shift+R）
+```
+
+**Firefox**：
+```
+1. F12 打开开发者工具
+2. Storage → 右键 → Delete All
+3. 刷新页面（Ctrl+Shift+R）
+```
+
+### 方法 3：浏览器设置清除
+
+**所有浏览器**：
+```
+1. Ctrl+Shift+Delete（Mac: Cmd+Shift+Delete）
+2. 选择"缓存的图片和文件"
+3. 时间范围选择"全部"
+4. 点击"清除数据"
+5. 刷新页面
+```
+
+### 方法 4：隐身模式测试
+
+```
+1. Ctrl+Shift+N（Chrome）或 Ctrl+Shift+P（Firefox）
+2. 访问网站
+3. 验证问题是否解决
+```
+
+## 开发者：强制更新
+
+### 1. 更新 Service Worker 版本
+
+```javascript
+// public/sw.js
+const CACHE_NAME = 'weiz-nav-v5';  // v4 → v5
+const RUNTIME_CACHE = 'weiz-nav-runtime-v5';
+const IMAGE_CACHE = 'weiz-nav-images-v5';
+```
+
+### 2. 更新 version.json
+
+```json
+{
+  "version": "1.0.5",
+  "cacheVersion": "v5"
+}
+```
+
+### 3. 部署
+
+```bash
+git add public/sw.js public/version.json
+git commit -m "chore: 强制清除缓存 v5"
+git push
+```
+
+### 4. 用户端自动更新
+
+用户访问网站时：
+1. 检测到新版本 Service Worker
+2. 自动下载并安装
+3. 删除旧缓存（v1, v2, v3, v4）
+4. 激活新版本（v5）
+5. 自动刷新页面
+
+## 验证缓存已清除
+
+### 浏览器控制台
+
+```javascript
+// 查看 Service Worker 版本
+navigator.serviceWorker.getRegistration().then(reg => {
+  console.log('SW:', reg?.active?.scriptURL);
+});
+
+// 查看缓存列表
+caches.keys().then(keys => {
+  console.log('Caches:', keys);
+  // 应该只看到 v4 的缓存
+});
+
+// 查看 CSP 策略
+fetch('/').then(r => {
+  console.log('CSP:', r.headers.get('content-security-policy'));
+});
+```
+
+### DevTools 检查
+
+```
+F12 → Application → Service Workers
+- 状态应该是 "activated and is running"
+- 版本应该是最新的
+
+F12 → Application → Cache Storage
+- 应该只有 v4 的缓存
+- 旧版本（v1, v2, v3）应该被删除
+```
+
+## 常见问题
+
+### Q: 为什么清除后还是有问题？
+
+**A**: 可能的原因：
+1. **CDN 缓存**：Cloudflare 边缘节点缓存了旧文件
+   - 解决：在 Cloudflare 控制台清除缓存
+   
+2. **浏览器扩展**：某些扩展会缓存资源
+   - 解决：禁用扩展或使用隐身模式
+
+3. **DNS 缓存**：DNS 解析到旧的 IP
+   - 解决：`ipconfig /flushdns`（Windows）或 `sudo dscacheutil -flushcache`（Mac）
+
+### Q: 如何防止缓存问题？
+
+**A**: 最佳实践：
+1. **版本化资源**：使用哈希文件名
+2. **合理的缓存策略**：
+   - HTML: `max-age=0`
+   - JS/CSS: `max-age=31536000` + 哈希
+   - 图片: `max-age=2592000`
+3. **Service Worker 版本管理**：每次更新递增版本号
+
+### Q: 用户需要手动清除吗？
+
+**A**: 不需要！
+- Service Worker 会自动更新
+- 旧缓存会自动清除
+- 用户只需刷新页面
+
+但如果遇到问题，可以：
+1. 访问 `/clear-cache.html`
+2. 点击"全部清除并刷新"
+
+### Q: 清除缓存会丢失数据吗？
+
+**A**: 不会！
+- ✅ LocalStorage 数据保留（用户的导航链接）
+- ✅ 用户设置保留
+- ❌ 只清除缓存的静态资源
+
+## 预防措施
+
+### 1. 开发时禁用缓存
+
+```
+DevTools → Network → Disable cache（勾选）
+```
+
+### 2. 使用版本号
+
+```javascript
+// 在 URL 中添加版本号
+<script src="/app.js?v=1.0.4"></script>
+```
+
+### 3. 设置正确的缓存头
+
+```
+# public/_headers
+/*.html
+  Cache-Control: public, max-age=0, must-revalidate
+
+/*.js
+  Cache-Control: public, max-age=31536000, immutable
+```
+
+### 4. 监控缓存状态
+
+```javascript
+// 定期检查缓存大小
+navigator.storage.estimate().then(estimate => {
+  const used = (estimate.usage / 1024 / 1024).toFixed(2);
+  const quota = (estimate.quota / 1024 / 1024).toFixed(2);
+  console.log(`缓存: ${used}MB / ${quota}MB`);
+});
+```
+
+## 清除缓存检查清单
+
+部署新版本后：
+
+- [ ] 更新 Service Worker 版本号
+- [ ] 更新 version.json
+- [ ] 提交并部署
+- [ ] 清除 Cloudflare 缓存（如果使用）
+- [ ] 测试环境验证
+- [ ] 生产环境验证
+- [ ] 监控用户反馈
+
+## 紧急清除脚本
+
+如果需要强制所有用户清除缓存：
+
+```javascript
+// 在 Service Worker 中添加
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    // 删除所有缓存
+    caches.keys().then((cacheNames) => {
+      return Promise.all(
+        cacheNames.map((cacheName) => {
+          return caches.delete(cacheName);
+        })
+      );
+    })
+  );
+});
+```
+
+## 总结
+
+**用户端**：
+- 访问 `/clear-cache.html` 清除缓存
+- 或等待 Service Worker 自动更新
+
+**开发者端**：
+- 每次更新递增 Service Worker 版本
+- 设置合理的缓存策略
+- 监控缓存状态
+
+**预防**：
+- 使用版本化资源
+- 正确的 HTTP 缓存头
+- Service Worker 自动更新机制
+
+---
+
+**记住**：缓存是为了性能，但也要确保用户能及时获取更新！
diff --git a/README.md b/README.md
index 481b5b0..b387e61 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,7 @@ pnpm deploy
 - [快速开始](./.kiro/specs/frontend-navigation-site/QUICKSTART.md) - 5 分钟快速部署
 - [部署指南](./.kiro/specs/frontend-navigation-site/DEPLOYMENT.md) - 详细部署说明
 - [PWA 使用指南](./.kiro/specs/frontend-navigation-site/PWA_GUIDE.md) - PWA 安装和使用
+- [缓存清除指南](./.kiro/specs/frontend-navigation-site/CACHE_CLEAR_GUIDE.md) - 解决缓存问题
 
 **开发文档**
 - [需求文档](./.kiro/specs/frontend-navigation-site/requirements.md) - 功能需求
diff --git a/components/navigation/LinkCard.tsx b/components/navigation/LinkCard.tsx
index e37a871..320086e 100644
--- a/components/navigation/LinkCard.tsx
+++ b/components/navigation/LinkCard.tsx
@@ -24,6 +24,8 @@ const IconWithFallback: React.FC<{
 }> = ({ src, alt, fallbackUrl, scale = 0.8 }) => {
   const [hasError, setHasError] = useState(false);
   const [faviconError, setFaviconError] = useState(false);
+  const [imageLoaded, setImageLoaded] = useState(false);
+  const [faviconLoaded, setFaviconLoaded] = useState(false);
 
   // 计算图标大小（基础大小 60px）
   const iconSize = Math.round(60 * scale);
@@ -46,9 +48,13 @@ const IconWithFallback: React.FC<{
         style={{ 
           transform: `scale(${scale})`,
         }}
+        onLoad={() => setFaviconLoaded(true)}
         onError={() => {
-          console.warn(`Favicon 加载失败: ${fallbackUrl}`);
-          setFaviconError(true);
+          // 只有在图片未成功加载时才标记为错误
+          if (!faviconLoaded) {
+            console.warn(`Favicon 加载失败: ${fallbackUrl}`);
+            setFaviconError(true);
+          }
         }}
       />
     );
@@ -65,9 +71,13 @@ const IconWithFallback: React.FC<{
       style={{ 
         transform: `scale(${scale})`,
       }}
+      onLoad={() => setImageLoaded(true)}
       onError={() => {
-        console.warn(`图标加载失败: ${src}`);
-        setHasError(true);
+        // 只有在图片未成功加载时才标记为错误
+        if (!imageLoaded) {
+          console.warn(`图标加载失败: ${src}`);
+          setHasError(true);
+        }
       }}
     />
   );
diff --git a/public/sw.js b/public/sw.js
index 1e35366..0ffc0ef 100644
--- a/public/sw.js
+++ b/public/sw.js
@@ -1,7 +1,7 @@
 // Service Worker for PWA
-const CACHE_NAME = 'weiz-nav-v3';
-const RUNTIME_CACHE = 'weiz-nav-runtime-v3';
-const IMAGE_CACHE = 'weiz-nav-images-v3';
+const CACHE_NAME = 'weiz-nav-v4';
+const RUNTIME_CACHE = 'weiz-nav-runtime-v4';
+const IMAGE_CACHE = 'weiz-nav-images-v4';
 
 // 需要预缓存的静态资源
 const PRECACHE_URLS = [
diff --git a/public/version.json b/public/version.json
index b0f9713..c5e33f3 100644
--- a/public/version.json
+++ b/public/version.json
@@ -1,7 +1,7 @@
 {
-  "version": "1.0.3",
-  "buildTime": "2025-11-18T10:00:00.000Z",
-  "cacheVersion": "v3",
+  "version": "1.0.4",
+  "buildTime": "2025-11-19T15:26:00.000Z",
+  "cacheVersion": "v4",
   "changelog": [
     "修复 CSP 策略，支持所有 HTTPS 资源",
     "优化图标缓存策略",