Fishのblog

1. 备份整个项目#

在更新前，务必先备份整个项目目录：

1
# Windows PowerShell
2
Copy-Item -Recurse "E:\Tools\blog\Twilight" "E:\Tools\blog\Twilight-backup"
3

4
# Linux / macOS
5
cp -r ~/blog/Twilight ~/blog/Twilight-backup

2. 记录自定义修改#

如果你对主题源码做过修改（如页面宽度、今日诗词等），请先查阅或更新 CUSTOM_CHANGES.md 文件，记录所有修改点。

3. 确认需要保留的个人数据#

⚠️ 重要：以下清单比作者官方指引更完整，包含了实际更新中容易遗漏的文件。

方案：临时目录法（推荐）#

这是最安全的方案，不会影响现有 .git 历史。

1
cd E:\Tools\blog
2
git clone https://github.com/radishzzz/astro-theme-twilight.git Twilight-new

1
cd E:\Tools\blog\Twilight
2

3
# PowerShell: 删除所有非 .git 的文件和目录
4
Get-ChildItem -Force | Where-Object { $_.Name -ne '.git' } | Remove-Item -Recurse -Force

1
# 复制新主题的所有文件（不含 .git）
2
Copy-Item -Path "E:\Tools\blog\Twilight-new\*" -Destination "E:\Tools\blog\Twilight" -Recurse -Exclude ".git"

1
# 恢复文章内容
2
Copy-Item -Path "E:\Tools\blog\Twilight-backup\src\content\*" -Destination "E:\Tools\blog\Twilight\src\content\" -Recurse -Force
3

4
# 恢复站点配置
5
Copy-Item -Path "E:\Tools\blog\Twilight-backup\twilight.config.yaml" -Destination "E:\Tools\blog\Twilight\" -Force
6

7
# 恢复静态资源
8
Copy-Item -Path "E:\Tools\blog\Twilight-backup\public\assets\*" -Destination "E:\Tools\blog\Twilight\public\assets\" -Recurse -Force
9

10
# 恢复看板娘（如有）
11
Copy-Item -Path "E:\Tools\blog\Twilight-backup\public\pio\*" -Destination "E:\Tools\blog\Twilight\public\pio\" -Recurse -Force
12

13
# 恢复相册（如有）
14
Copy-Item -Path "E:\Tools\blog\Twilight-backup\public\albums\*" -Destination "E:\Tools\blog\Twilight\public\albums\" -Recurse -Force
15

16
# 恢复 CMS 配置（如有）
17
Copy-Item -Path "E:\Tools\blog\Twilight-backup\public\admin\config.yml" -Destination "E:\Tools\blog\Twilight\public\admin\" -Force

1
# 恢复 GitHub Actions 工作流（非常重要！）
2
Copy-Item -Path "E:\Tools\blog\Twilight-backup\.github" -Destination "E:\Tools\blog\Twilight\" -Recurse -Force
3

4
# 恢复 astro.config.mjs（含 base 路径配置，子目录部署必须！）
5
Copy-Item -Path "E:\Tools\blog\Twilight-backup\astro.config.mjs" -Destination "E:\Tools\blog\Twilight\" -Force
6

7
# 恢复部署和备份脚本
8
Copy-Item -Path "E:\Tools\blog\Twilight-backup\deploy.bat" -Destination "E:\Tools\blog\Twilight\" -Force
9
Copy-Item -Path "E:\Tools\blog\Twilight-backup\backup.bat" -Destination "E:\Tools\blog\Twilight\" -Force
10

11
# 恢复自定义修改备忘录
12
Copy-Item -Path "E:\Tools\blog\Twilight-backup\CUSTOM_CHANGES.md" -Destination "E:\Tools\blog\Twilight\" -Force
13

14
# 恢复 README
15
Copy-Item -Path "E:\Tools\blog\Twilight-backup\README.md" -Destination "E:\Tools\blog\Twilight\" -Force

1
Remove-Item -Recurse -Force "E:\Tools\blog\Twilight-new"

1. 页面宽度调整#

文件：src/constants/constants.ts

1
// 将 PAGE_WIDTH 从 90 改为 100
2
export const PAGE_WIDTH = 100;

2. 音乐播放器可见性暂停#

文件：src/components/musicPlayer.svelte

切换标签页或最小化时自动暂停播放，回来后恢复。

详细修改：

1. 在 showError 状态后添加 wasPlayingBeforeHidden 变量
2. 在 STORAGE_KEYS 后添加 handleVisibilityChange() 函数
3. 在 onMount 的 handleAudioEvents(); 后添加：document.addEventListener("visibilitychange", handleVisibilityChange);
4. 在 onDestroy 中添加：document.removeEventListener("visibilitychange", handleVisibilityChange);

3. 今日诗词#

文件：src/components/common/typewriterText.astro 和 src/components/banner.astro

在 Banner 副标题中显示今日诗词 API 的内容。

详细修改：

1. typewriterText.astro：
   • Props 新增 jinrishici?: boolean
   • span 添加 data-jinrishici 属性
   • TypewriterEffect 类添加异步加载 https://v2.jinrishici.com/one.json 的逻辑
   • 修复初始化时机：使用 astro:after-swap 替代 swup:contentReplaced
2. banner.astro：TypewriterText 组件添加 jinrishici={true}

4. 子目录部署修复（如需要）#

如果博客部署在子目录（如 /blog/），需要修复硬编码路径：

• astro.config.mjs: 设置 base: "/blog/"
• src/layouts/base.astro: Pio 样式路径
• src/components/pio.svelte: Pio 脚本和模型路径
• src/utils/particle.ts: 粒子特效图片路径

将硬编码的 /xxx 改为 `${import.meta.env.BASE_URL}xxx`。

问题 1：GitHub Actions 工作流丢失#

现象：部署时发现本地在跑 pnpm build，而不是交给 GitHub Actions。

原因：新主题不包含 .github/workflows/deploy.yml（因为每个人部署方式不同），更新时被删除了。

解决：

1. 从备份恢复 .github/workflows/ 目录
2. 或从 git 历史恢复：git show HEAD~1:.github/workflows/deploy.yml
3. 修改 deploy.bat，移除本地 build 步骤

问题 2：Duplicate id 警告#

现象：pnpm dev 时出现警告：

1
[WARN] [glob-loader] Duplicate id "成长日记/深度学习/pytorch" found in ...

原因：Astro 内容缓存残留。

解决：清理 .astro 缓存目录后重启：

1
rm -rf .astro
2
pnpm dev

问题 3：代码块语言标识符警告#

现象：构建时出现大量警告：

1
[WARN] Received unknown language "Bash"
2
[WARN] Received unknown language "TOML"

原因：Markdown 中的代码块语言标识符使用了大写（如 ```Bash），但 astro-expressive-code 要求小写。

解决：批量替换所有文章中的语言标识符：

• Bash → bash
• TOML → toml
• Plain → text
• PowerShell → powershell

问题 4：公告链接 404#

现象：点击侧边栏公告的”Learn More”链接，返回 404。

原因：twilight.config.yaml 中公告链接是 /blog/about/，但 astro.config.mjs 的 base 配置是 /。

解决：

• 如果 base: "/"，链接应该是 /about/
• 如果 base: "/blog/"，链接应该是 /blog/about/

确保 twilight.config.yaml 中的 siteURL 和 astro.config.mjs 中的 base 配置一致。

问题 5：deploy.bat 脚本逻辑错误#

现象：deploy.bat 在本地执行 pnpm build，但实际应该交给 GitHub Actions 构建。

原因：之前创建脚本时没意识到有 GitHub Actions 工作流。

解决：修改 deploy.bat，只保留 git add → git commit → git push 三步，构建交给云端。

问题 6：base 路径导致网站卡死 loading 🔥🔥🔥#

现象：部署后网站一直停在 loading 页面，无法进入。

原因：博客部署在 zenfish-zy.github.io/blog/（子目录），但新主题默认 base: "/"。所有 JS/CSS 资源路径指向 /_astro/xxx.js（根目录），而实际应该指向 /blog/_astro/xxx.js，导致全部资源 404。只有 HTML 能加载，所以 loading 页面显示了但 JS 永远不会执行。

解决：在 astro.config.mjs 中设置 base: "/blog/"。

⚠️ 这不是可选的美化配置，而是子目录部署的必要条件！ 如果仓库名不是 <username>.github.io，GitHub Pages 会在 /<repo-name>/ 子目录下提供服务，必须设置 base 匹配。

问题 7：README.md 被覆盖#

现象：GitHub 仓库的 README 变成了主题作者的介绍。

原因：新主题自带 README.md，覆盖了个人 README。

解决：从 git 历史恢复：

1
git show HEAD~1:README.md > README.md

问题 8：旧版相册配置残留#

现象：构建时报错 Image file not found: src/content/albums/智子_ASK.jpg。

原因：备份恢复时，旧版的 src/content/albums/example.json 和新版的 src/content/albums/example/jsonExample.json 共存了。新版相册结构变成了子文件夹形式，旧版配置引用的路径已失效。

解决：删除旧版 src/content/albums/example.json，保留新版 example/ 子文件夹。

1. 安装依赖#

1
cd E:\Tools\blog\Twilight
2
pnpm install

2. 启动开发服务器#

1
pnpm dev

3. 检查清单#

• 首页正常显示，Banner 有今日诗词
• 切换标签页时音乐自动暂停
• 文章页面宽度符合预期
• 代码块无语言标识符警告
• 侧边栏公告链接可正常跳转
• 分类筛选功能正常

4. 验证自定义修改#

1
# 验证页面宽度
2
grep -n "PAGE_WIDTH" src/constants/constants.ts
3

4
# 验证音乐播放器可见性暂停
5
grep -n "visibilitychange" src/components/musicPlayer.svelte
6

7
# 验证今日诗词
8
grep -n "jinrishici" src/components/common/typewriterText.astro
9
grep -n "jinrishici" src/components/banner.astro
10

11
# 验证 GitHub Actions 存在
12
ls .github/workflows/

与作者指引的主要差异#

建议#

1. 每次做源码修改时，及时更新 CUSTOM_CHANGES.md
2. backup.bat 脚本应该备份所有重要文件（包括脚本自身和 README）
3. 更新前先检查 .github/workflows/ 是否存在
4. 子目录部署务必检查 base 配置，这是最容易导致网站无法访问的问题
5. 恢复备份后，建议对比新旧 astro.config.mjs，只保留个人配置（如 base），其他保持新版

最后更新: 2026-02-05