常见问题
1. 常见问题❌ 改了代码但页面没变化根因：本地开发文件在 D:/网文剧本/bloodbound(CodeBuddy版本)/，Python 服务器从项目根目录运行（192.168.1.98:8080），同时服务 canvas/ 和 screenplay/ 两个子站。
解决：修改本地文件后刷新浏览器即可看到变化。如遇缓存，用 Ctrl+Shift+R 强制刷新。NAS（192.168.1.3）为备用静态服务，文件可能过时。❌ 三站按钮样式不统一根因：各页面各自定义了站点切换按钮 CSS，命名不同（switch-btn / site-btn），参数不一致。
统一标准：border-radius: 8px; border: 2px solid #3a7bb830; background: #3a7bb808; color: #3a7bb8; padding: 4px 12px; gap: 4px;
新增任何站点切换按钮时，直接复制这套 CSS。❌ 页面被旧缓存覆盖根因：浏览器缓存了旧版本 HTML。虽然已添加 Cache-Control: no-cache，但有时不生效。
解决：每次覆盖文件后，用 Ctrl+Shift+R 强制刷新，或打开无痕窗口验证。❌ 页面突然"全白"或"失联"根因：通常是 Git 操作覆盖了正在使用的文件、JS 括号不匹配、或 CSS 变量未定义导致整页样式崩溃。
解决：优先 git checkout e1ab67d -- 文件名 恢复稳定版本，再逐步应用改动。不要在损坏状态上修修补补。❌ 8080 首页数据全显示 0 / --根因：首页曾依赖 fetch('/api/stats/...') 和 chapters.json 等动态接口加载数据，当接口返回空、超时或 JSON 文件缺失/损坏时，所有数字会显示为 0 或 --。此问题已反复发生多次。
解决：所有数据已改为 <script> 内硬编码，零 API 依赖。章节进度、角色登场、设定字数、正文字数等全部写死在 JS 中。如需修改数据，直接编辑 index.html 中 <script> 标签内的数字，严禁重新接入任何 fetch() 动态接口。❌ 首页数据对不上 · 数字/进度/字数是错的根因：硬编码的数据与实际情况脱节（如章节数、字数、角色数有变动但未同步更新）。
解决：数据更新入口只有一个，直接改 \\DS920\web\bloodbound\canvas\index.html 中 <script> 标签内的硬编码数字。改完必须覆盖到 NAS。每次小说内容有变动时，顺手更新首页对应数据。❌ 导航栏下拉菜单不可点击/不可见根因：.toolbar-left 设置了 overflow-x: auto，导致下拉菜单被裁剪在父容器内部，不可见也不可点击。
解决：将 .toolbar-left 的 overflow-x: auto 改为 overflow: visible，同时确保 .toolbar 和 .toolbar-inner 也设为 overflow: visible。删除 .toolbar-left::-webkit-scrollbar。🔷 Git 上传完整方案（当前正确配置）架构：8080 首页按钮 → http://127.0.0.1:8787 本地服务 → git add/commit/push → Gitee
关键路径：
· Git 仓库：c:\Users\徐\CodeBuddy\20260701140428
· Node.js：\\Ds920\中台程序\C-组内文件存储\郑岩\node-v24.18.0-win-x64\node-v24.18.0-win-x64\node.exe
· 服务脚本：c:\Users\徐\CodeBuddy\20260701140428\git-server.js
· 启动脚本：c:\Users\徐\CodeBuddy\20260701140428\启动Git上传服务.bat
· 监听端口：localhost:8787
· Gitee 远程：https://gitee.com/beijing-zangdai_0/the-book-of-blood-covenant.git
使用流程：
① 打开 8080 首页 → 点击 Git 上传
② 若提示服务未启动 → 点「启动上传服务」打开文件夹 → 双击 启动Git上传服务.bat
③ 点「启动后重试」→ 自动 add + commit + push
故障排查：服务无法启动时，检查 Node.js 路径是否存在、端口 8787 是否被占用。❌ Git 上传失败 · 历史坑（已废弃方案，勿用）根因：本地工作区 D:/网文剧本/bloodbound(CodeBuddy版本)/ 是 Git 源头，直接从这里推送。NAS 只是备用静态服务，不应作为 Git 源头。
结论：Git 只从本地工作区推送。NAS 只负责提供静态文件访问。❌ 所有按钮都不使用图标（emoji）规则：规范总站的所有站点切换按钮、导航链接均不使用 emoji 图标（如 📖🎬📋）。按钮仅保留纯文字。
原因：图标在不同平台渲染不一致，且与简洁专业的页面风格冲突。小说站和影视站可保留图标，规范总站一律不添加。❌ 影视站/规范站 导航链接 404根因：canvas 和 screenplay 分属不同子目录，但由同一台 Python 服务器（192.168.1.98:8080）提供服务。服务器通过 HTTP Referer 自动回退到正确的子目录。
解决：跨站导航链接使用服务器根路径（如 /screenplay/adaptation-film/），服务器会自动解析。同站引用可保持相对路径。❌ 导航栏样式丢失 / 配色错误 / 页面无颜色根因：8080 和 8766 共用的基础设施文件（style.css、theme.js、nav.js）不在 master 分支，在 op-02/feat-init 分支中。当这些文件意外丢失时，AI 如果自行创建，必然导致 CSS 变量不一致、主题键名错误（如 data-theme="dark" 而非 data-theme="night"）、缺少额外变量等连锁问题。
获取原版：git show op-02/feat-init:canvas/style.css > style.css（同样方式获取 theme.js 和 canvas/nav.js），然后复制到对应 NAS 目录。
严禁：AI 自己创建 style.css / theme.js / nav.js。必须从 op-02/feat-init 分支提取。
❌ 改了代码但页面没变化
根因：本地开发文件在
解决：修改本地文件后刷新浏览器即可看到变化。如遇缓存，用 Ctrl+Shift+R 强制刷新。NAS（192.168.1.3）为备用静态服务，文件可能过时。
D:/网文剧本/bloodbound(CodeBuddy版本)/，Python 服务器从项目根目录运行（192.168.1.98:8080），同时服务 canvas/ 和 screenplay/ 两个子站。解决：修改本地文件后刷新浏览器即可看到变化。如遇缓存，用 Ctrl+Shift+R 强制刷新。NAS（192.168.1.3）为备用静态服务，文件可能过时。
❌ 三站按钮样式不统一
根因：各页面各自定义了站点切换按钮 CSS，命名不同（
统一标准：
新增任何站点切换按钮时，直接复制这套 CSS。
switch-btn / site-btn），参数不一致。统一标准：
border-radius: 8px; border: 2px solid #3a7bb830; background: #3a7bb808; color: #3a7bb8; padding: 4px 12px; gap: 4px;新增任何站点切换按钮时，直接复制这套 CSS。
❌ 页面被旧缓存覆盖
根因：浏览器缓存了旧版本 HTML。虽然已添加
解决：每次覆盖文件后，用 Ctrl+Shift+R 强制刷新，或打开无痕窗口验证。
Cache-Control: no-cache，但有时不生效。解决：每次覆盖文件后，用 Ctrl+Shift+R 强制刷新，或打开无痕窗口验证。
❌ 页面突然"全白"或"失联"
根因：通常是 Git 操作覆盖了正在使用的文件、JS 括号不匹配、或 CSS 变量未定义导致整页样式崩溃。
解决：优先
解决：优先
git checkout e1ab67d -- 文件名 恢复稳定版本，再逐步应用改动。不要在损坏状态上修修补补。❌ 8080 首页数据全显示 0 / --
根因：首页曾依赖
解决：所有数据已改为
fetch('/api/stats/...') 和 chapters.json 等动态接口加载数据，当接口返回空、超时或 JSON 文件缺失/损坏时，所有数字会显示为 0 或 --。此问题已反复发生多次。解决：所有数据已改为
<script> 内硬编码，零 API 依赖。章节进度、角色登场、设定字数、正文字数等全部写死在 JS 中。如需修改数据，直接编辑 index.html 中 <script> 标签内的数字，严禁重新接入任何 fetch() 动态接口。❌ 首页数据对不上 · 数字/进度/字数是错的
根因：硬编码的数据与实际情况脱节（如章节数、字数、角色数有变动但未同步更新）。
解决：数据更新入口只有一个，直接改
解决：数据更新入口只有一个，直接改
\\DS920\web\bloodbound\canvas\index.html 中 <script> 标签内的硬编码数字。改完必须覆盖到 NAS。每次小说内容有变动时，顺手更新首页对应数据。❌ 导航栏下拉菜单不可点击/不可见
根因：
解决：将
.toolbar-left 设置了 overflow-x: auto，导致下拉菜单被裁剪在父容器内部，不可见也不可点击。解决：将
.toolbar-left 的 overflow-x: auto 改为 overflow: visible，同时确保 .toolbar 和 .toolbar-inner 也设为 overflow: visible。删除 .toolbar-left::-webkit-scrollbar。🔷 Git 上传完整方案（当前正确配置）
架构：8080 首页按钮 →
关键路径：
· Git 仓库：
· Node.js：
· 服务脚本：
· 启动脚本：
· 监听端口：
· Gitee 远程：
使用流程：
① 打开 8080 首页 → 点击 Git 上传
② 若提示服务未启动 → 点「启动上传服务」打开文件夹 → 双击 启动Git上传服务.bat
③ 点「启动后重试」→ 自动 add + commit + push
故障排查：服务无法启动时，检查 Node.js 路径是否存在、端口 8787 是否被占用。
http://127.0.0.1:8787 本地服务 → git add/commit/push → Gitee关键路径：
· Git 仓库：
c:\Users\徐\CodeBuddy\20260701140428· Node.js：
\\Ds920\中台程序\C-组内文件存储\郑岩\node-v24.18.0-win-x64\node-v24.18.0-win-x64\node.exe· 服务脚本：
c:\Users\徐\CodeBuddy\20260701140428\git-server.js· 启动脚本：
c:\Users\徐\CodeBuddy\20260701140428\启动Git上传服务.bat· 监听端口：
localhost:8787· Gitee 远程：
https://gitee.com/beijing-zangdai_0/the-book-of-blood-covenant.git使用流程：
① 打开 8080 首页 → 点击 Git 上传
② 若提示服务未启动 → 点「启动上传服务」打开文件夹 → 双击 启动Git上传服务.bat
③ 点「启动后重试」→ 自动 add + commit + push
故障排查：服务无法启动时，检查 Node.js 路径是否存在、端口 8787 是否被占用。
❌ Git 上传失败 · 历史坑（已废弃方案，勿用）
根因：本地工作区
结论：Git 只从本地工作区推送。NAS 只负责提供静态文件访问。
D:/网文剧本/bloodbound(CodeBuddy版本)/ 是 Git 源头，直接从这里推送。NAS 只是备用静态服务，不应作为 Git 源头。结论：Git 只从本地工作区推送。NAS 只负责提供静态文件访问。
❌ 所有按钮都不使用图标（emoji）
规则：规范总站的所有站点切换按钮、导航链接均不使用 emoji 图标（如 📖🎬📋）。按钮仅保留纯文字。
原因：图标在不同平台渲染不一致，且与简洁专业的页面风格冲突。小说站和影视站可保留图标，规范总站一律不添加。
原因：图标在不同平台渲染不一致，且与简洁专业的页面风格冲突。小说站和影视站可保留图标，规范总站一律不添加。
❌ 影视站/规范站 导航链接 404
根因：canvas 和 screenplay 分属不同子目录，但由同一台 Python 服务器（192.168.1.98:8080）提供服务。服务器通过 HTTP Referer 自动回退到正确的子目录。
解决：跨站导航链接使用服务器根路径（如
解决：跨站导航链接使用服务器根路径（如
/screenplay/adaptation-film/），服务器会自动解析。同站引用可保持相对路径。❌ 导航栏样式丢失 / 配色错误 / 页面无颜色
根因：8080 和 8766 共用的基础设施文件（
获取原版：
严禁：AI 自己创建 style.css / theme.js / nav.js。必须从 op-02/feat-init 分支提取。
style.css、theme.js、nav.js）不在 master 分支，在 op-02/feat-init 分支中。当这些文件意外丢失时，AI 如果自行创建，必然导致 CSS 变量不一致、主题键名错误（如 data-theme="dark" 而非 data-theme="night"）、缺少额外变量等连锁问题。获取原版：
git show op-02/feat-init:canvas/style.css > style.css（同样方式获取 theme.js 和 canvas/nav.js），然后复制到对应 NAS 目录。严禁：AI 自己创建 style.css / theme.js / nav.js。必须从 op-02/feat-init 分支提取。