二、搭建项目与本地预览#

前置环境：需要 Node.js 20+（去 nodejs.org 下载安装）和 pnpm 包管理器：

1
# 安装 pnpm（Node.js 自带 corepack，也可用 npm 装）
2
npm install -g pnpm
3
pnpm --version   # 确认安装成功

Firefly 主题的仓库地址：CuteLeaf/Firefly。克隆后安装依赖：

1
# 克隆模板（我的目录是 my-firefly-blog）
2
git clone https://github.com/CuteLeaf/Firefly.git my-firefly-blog
3
cd my-firefly-blog
4

5
# 安装依赖并启动本地预览
6
pnpm install
7
pnpm dev

浏览器打开 http://localhost:4321 即可看到站点。之后每次改配置，本地跑 pnpm build + pnpm preview 验证，确认无误再推送。

三、双站并存：旧博客不丢#

迁移期间新站还没完全就绪，旧站不能直接关。方案是双站并存：

• 新站（Astro）：部署在 lycaonide.github.io 仓库，即主站 https://lycaonide.github.io；
• 旧站（Hexo）：保留原内容，作为项目页部署到 https://lycaonide.github.io/hexo-blog/。

等新站内容补齐后，再逐步把旧站文章迁过来，最后下线旧站即可。迁移过程零停服，随时可以回滚。

四、字体本地化（最大的坑：jsdelivr 被墙）#

这是迁移过程中最折腾的一环。主题默认从 jsdelivr CDN 下载 3 个在线字体（Zen Maru Gothic / Inter / JetBrains Mono），而 jsdelivr 在国内经常被墙，导致：

• 构建卡在字体下载、超时失败；
• 线上页面字体加载不出来，回退成默认字体，很丑。

试过的方案和结论：

最终做法：

1. 把 4 个 woff2 字体文件放进 public/assets/fonts/（字体可从主题自带的 assets 目录复制，或从 Google Fonts 下载对应字重的 woff2）；
2. 新建 src/styles/local-fonts.css，手写 @font-face：

1
@font-face {
2
  font-family: "Noto Sans SC";
3
  src: url("/assets/fonts/noto-sans-sc-500.woff2") format("woff2");
4
  font-weight: 500;
5
  font-display: swap;
6
}
7
@font-face {
8
  font-family: "Space Grotesk";
9
  src: url("/assets/fonts/space-grotesk-500.woff2") format("woff2");
10
  font-weight: 500;
11
  font-display: swap;
12
}
13
@font-face {
14
  font-family: "JetBrains Mono";
15
  src: url("/assets/fonts/jetbrains-mono-400.woff2") format("woff2");
16
  font-weight: 400;
17
  font-display: swap;
18
}
19
@font-face {
20
  font-family: "JetBrains Mono";
21
  src: url("/assets/fonts/jetbrains-mono-700.woff2") format("woff2");
22
  font-weight: 700;
23
  font-display: swap;
24
}

1. fontConfig.ts 里把 selected 设为 ["system"]，让全局走系统字体；
2. 写一个子集化脚本：扫描构建产物里的所有 HTML，收集实际用到的字符，只保留这些字符生成轻量 woff2（核心代码用了 subset-font 库）：

1
// scripts/subset-fonts.ts（核心逻辑）
2
import subsetFont from "subset-font";
3
import { glob } from "glob";
4
import { readFile, writeFile } from "node:fs/promises";
5

6
// 1. 收集 dist/ 里所有 HTML 的实际字符
7
const htmlFiles = await glob(`${DIST_DIR}/**/*.html`);
8
const charSet = new Set<string>();
9
for (const file of htmlFiles) {
10
  const html = await readFile(file, "utf-8");
11
  for (const c of html.replace(/<[^>]+>/g, " ")) charSet.add(c);
12
}
13

14
// 2. 用 subset-font 生成子集 woff2，再替换 CSS/HTML 里的引用
15
const subset = await subsetFont(fontBuffer, [...charSet].join(""), {
16
  targetFormat: "woff2",
17
});
18
await writeFile(outFile, subset);

这个脚本已集成进 pnpm build（构建链会自动执行），也可以单独跑：npx tsx scripts/subset-fonts.ts。结果：字体体积从 3MB 压到约 140KB（换了思源黑体后更小），页面加载快了很多。

1
/* 放在全局样式入口文件顶部 */
2
@import url("https://cdn.jsdelivr.net/npm/@fontsource/zen-maru-gothic@5/index.css");
3
@import url("https://cdn.jsdelivr.net/npm/@fontsource/jetbrains-mono@5/index.css");
4
@import url("https://cdn.jsdelivr.net/npm/@fontsource/inter@5/index.css");

五、站点美化：装饰总开关#

主题本身是二次元风格，加了几个装饰效果：樱花飘落、水波纹背景、卡片立体感。为了让它们可管理，我统一收敛到一个配置文件 src/config/decorationConfig.ts：

1
export const decorationConfig = {
2
  sakura: true,   // 樱花飘落
3
  live2d: true,   // 看板娘
4
  waves: true,    // 背景水波纹
5
  card3d: true,   // 卡片立体感
6
};

想换”极简技术风”时，全部改成 false 就行，不用到处找开关。

六、评论系统：Giscus#

评论用的是 Giscus（基于 GitHub Discussions，免费、无广告、数据在自己仓库里）。接入步骤：

1. 开启 Discussions：仓库 Settings → Features → Discussions 勾选开启。开启后仓库导航栏会出现 Discussions 入口：

1. 安装 giscus App：giscus.app → Install，授权给博客仓库；
2. 生成配置：在 giscus 配置页填仓库名，页面会校验仓库状态（必须公开、已装 App、已开 Discussions），三项都满足会显示”成功”：

1. 写入主题配置 src/config/commentConfig.ts：

1
export const commentConfig = {
2
  type: "giscus",
3
  repo: "lycaonide/lycaonide.github.io",
4
  repoId: "R_kgDORApdOw",
5
  category: "Announcements",
6
  categoryId: "DIC_kwDORApdO84DFWdq",
7
  mapping: "title",        // 按文章标题匹配讨论
8
  reactionsEnabled: "1",
9
  inputPosition: "top",
10
  lang: "zh-CN",
11
  loading: "lazy",
12
};

补充：分类我选了 Announcements（公告分类），可以防止陌生人随意开新讨论刷屏。

七、友链页面#

主题自带了友链页，只是默认关闭。开启方法：

1
friends: true,   // 原来是 false

同时新建 src/content/spec/friends.md 写入友链说明（本站信息、申请方式、小要求），页面底部就会显示自定义的友链交换说明。

注意：友链内容页缺失会导致构建报错 friends page content not found，所以 开关和内容文件要一起建。

八、GitHub Actions 自动部署#

推送后自动构建发布，用的是 Actions workflow（.github/workflows/deploy.yml），这是本站实际在用的完整配置：

1
name: Deploy to GitHub Pages
2

3
on:
4
  push:
5
    branches: [ main, master ]
6
  workflow_dispatch:
7

8
# Pages 部署需要的权限
9
permissions:
10
  contents: read
11
  pages: write
12
  id-token: write
13

14
# 确保只有一个部署任务同时运行
15
concurrency:
16
  group: "pages"
17
  cancel-in-progress: false
18

19
jobs:
20
  build:
21
    runs-on: ubuntu-latest
22
    steps:
23
      - name: Checkout
24
        uses: actions/checkout@v4
25

26
      - name: Setup Node.js
27
        uses: actions/setup-node@v4
28
        with:
29
          node-version: '22'
30

31
      - name: Setup pnpm
32
        uses: pnpm/action-setup@v4
33
        with:
34
          version: 11.22.0
35
          run_install: false
36

37
      - name: Install dependencies
38
        run: pnpm install --no-frozen-lockfile
39

40
      - name: Build site
41
        run: pnpm run build
42

43
      - name: Create .nojekyll file
44
        run: touch dist/.nojekyll
45

46
      - name: Upload artifact
47
        uses: actions/upload-pages-artifact@v3
48
        with:
49
          path: dist  # Astro默认构建输出目录
50

51
  deploy:
52
    environment:
53
      name: github-pages
54
      url: ${{ steps.deployment.outputs.page_url }}
55
    runs-on: ubuntu-latest
56
    needs: build
57
    steps:
58
      - name: Deploy to GitHub Pages
59
        id: deployment
60
        uses: actions/deploy-pages@v4

几个关键点：

• touch dist/.nojekyll：GitHub Pages 默认用 Jekyll 处理，不建这个文件会把 _astro 这类目录忽略掉，页面会白屏；
• concurrency：防止多次 push 时部署任务互相打架；
• workflow_dispatch：想手动触发重新部署时，Actions 页面点一下即可。

每次 push 后，仓库的 Actions 页面会看到构建部署记录（绿色对勾表示成功，点进去能看每步日志）：

以后写文章只需要：

1
git add .
2
git commit -m "新文章"
3
git push

前置：git push 走 SSH，需要先在 GitHub 配置好 SSH 密钥（生成密钥、把公钥加到 GitHub → SSH and GPG keys，方法可参考本站《学习用Hexo写博客》一文第五节）。

等待 3-4 分钟，Actions 构建部署完成，线上自动更新，全程不用手动操作。

十、Cloudflare Pages 部署（国内访问加速）#

GitHub Pages 的服务器在境外，国内访问时快时慢，图片、字体偶尔要等很久。为了让国内访客更流畅，给本站加了一层 Cloudflare Pages 双部署：GitHub Pages 保持不变（原有链接不断），Cloudflare Pages 作为国内加速入口，两个域名内容同步。

双部署有什么用：

• 国内加速：Cloudflare 有全球 CDN（含国内优化节点），页面、图片、字体加载明显更快，这是最主要的价值；
• 双保险：一个平台出问题（GitHub 被墙、Pages 服务异常、DNS 污染），另一个域名随时能顶上，站点不”失联”；
• 评论/友链不受影响：Giscus 评论挂在 GitHub 仓库上、友链数据在配置里，两个域名共用同一套，换域名不丢数据。

两个网址内容完全一致，按网络环境任选：

• GitHub Pages：https://lycaonide.github.io
• Cloudflare Pages：https://my-firefly-blog.pages.dev

1
# 1. 构建（输出 dist/）
2
pnpm build
3

4
# 2. 配置凭据（PowerShell 用 $env: 前缀）
5
export CLOUDFLARE_API_TOKEN="你的API_TOKEN"      # 上一步创建的
6
export CLOUDFLARE_ACCOUNT_ID="你的账号ID"        # CF 控制台 URL 里 /xxx/ 那段
7

8
# 3. 创建 Pages 项目（仅首次）
9
npx wrangler pages project create my-firefly-blog --production-branch main
10

11
# 4. 部署 dist 目录
12
npx wrangler pages deploy dist --project-name my-firefly-blog --branch main

1
✨ Success! Uploaded 244 files (17.28 sec)
2

3
🌎 Deploying...
4
✨ Deployment complete! Take a peek over at https://ca824054.my-firefly-blog.pages.dev

3. 验证#

浏览器打开 https://my-firefly-blog.pages.dev，内容和 GitHub Pages 完全一致（同一个 dist 构建产物），国内访问明显更流畅：

Cloudflare 控制台的部署记录页（Production 域名 + 每次部署的提交信息、状态、预览地址）：

1
name: Deploy to Cloudflare Pages
2

3
on:
4
  push:
5
    branches: [main]
6
  workflow_dispatch:
7

8
jobs:
9
  deploy:
10
    runs-on: ubuntu-latest
11
    permissions:
12
      contents: read
13
    steps:
14
      - name: Checkout
15
        uses: actions/checkout@v4
16

17
      - name: Setup Node.js
18
        uses: actions/setup-node@v4
19
        with:
20
          node-version: '22'
21

22
      - name: Setup pnpm
23
        uses: pnpm/action-setup@v4
24
        with:
25
          version: 11.22.0
26
          run_install: false
27

28
      - name: Install dependencies
29
        run: pnpm install --no-frozen-lockfile
30

31
      - name: Build
32
        run: pnpm run build
33

34
      - name: Deploy to Cloudflare Pages
35
        uses: cloudflare/wrangler-action@v3
36
        with:
37
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
38
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
39
          command: pages deploy dist --project-name my-firefly-blog --branch main

十一、总结#

这次迁移的核心经验：

1. 配置收敛：装饰、评论、友链等开关集中在 config 文件里，方便统一管理；
2. 双站过渡：新旧站并存，内容迁完再下线，风险可控；
3. 自动化部署：GitHub Actions 让发布变成”push 就完事”。

最终效果就是你现在看到的这个站：Astro 7 + Firefly 主题 + GitHub Pages，樱花、评论、友链齐全，加载快还免费。

二、编辑博客内容#

操作： 打开文章文件：用任意 Markdown 编辑器打开 source/_posts/你的博客标题.md 文件。 配置文章信息：文件开头的「Front-matter」是 Hexo 识别文章属性的区域（必须保留），格式说明：

• ---：固定开头和结尾标记，不可省略
• title:：文章标题，中文/英文均可，冒号后必须加空格
• date:：发布日期，格式为 YYYY-MM-DD HH:mm:ss，冒号后必须加空格
• tags:：文章标签，中文/英文均可，多个标签用 [标签1, 标签2] 数组格式，冒号后必须加空格
• categories:：文章分类，中文/英文均可，冒号后必须加空格

1
---
2
title: 你的博客标题
3
date: 2026-03-25 14:00:00
4
tags: [标签1, 标签2]
5
categories: 分类名称
6
---
7
# 一级标题（中文/英文均可）
8
正文内容（支持 Markdown 语法）
9

10
## 二级标题（中文/英文均可）
11
- 列表项1
12
- 列表项2
13

14
### 三级标题（中文/英文均可）
15
[链接文字](链接地址)
16
![图片描述](/images/图片文件名.jpg)

三、本地预览博客效果#

操作： 在 Git Bash 的 Hexo 项目目录下，输入命令启动本地服务：

1
hexo clean  # 先清理旧缓存（建议执行）
2
hexo s      # 启动本地预览

验证： 打开浏览器访问 http://localhost:4000，在「文章」列表中找到对应文章，点击进入查看格式、图片、链接是否正常显示。

关闭预览： 在 Git Bash 中按 Ctrl+C 终止服务。

四、发布新博客到线上#

1
# 1. 清空旧代理配置（避免之前残留的错误端口影响）
2
git config --global --unset http.proxy
3
git config --global --unset https.proxy
4

5
# 2. 配置红岸加速器代理（本地端口为 7892，与加速器配置一致）
6
git config --global http.proxy http://127.0.0.1:7892
7
git config --global https.proxy http://127.0.0.1:7892
8

9
# 3. 清理本地缓存 + 生成静态文件 + 部署到 GitHub
10
hexo clean  # 清理本地缓存，确保生成最新文件
11
hexo g      # 重新生成包含新文章的静态页面
12
hexo d      # 部署到 GitHub 仓库

1
# 1. 进入项目目录
2
cd ~/Desktop/my-hexo-blog
3

4
# 2. 新建文章
5
hexo new "你的博客标题"
6

7
# 3. 编辑文章后，本地预览
8
hexo clean
9
hexo s
10

11
# 4. 预览无误后，部署上线
12
git config --global --unset http.proxy
13
git config --global --unset https.proxy
14
git config --global http.proxy http://127.0.0.1:7892
15
git config --global https.proxy http://127.0.0.1:7892
16
hexo clean && hexo g && hexo d

1
# 1. 进入项目目录
2
cd ~/Desktop/my-hexo-blog
3

4
# 2. 编辑文章后，本地预览
5
hexo clean
6
hexo s
7

8
# 3. 预览无误后，部署上线
9
git config --global --unset http.proxy
10
git config --global --unset https.proxy
11
git config --global http.proxy http://127.0.0.1:7892
12
git config --global https.proxy http://127.0.0.1:7892
13
hexo clean && hexo g && hexo d

1
#!/bin/bash
2
# 清空旧代理
3
git config --global --unset http.proxy
4
git config --global --unset https.proxy
5

6
# 配置红岸加速器代理
7
git config --global http.proxy http://127.0.0.1:7892
8
git config --global https.proxy http://127.0.0.1:7892
9

10
# 执行部署
11
hexo clean && hexo g && hexo d
12

13
# 部署完成后取消代理（可选）
14
git config --global --unset http.proxy
15
git config --global --unset https.proxy
16

17
echo "部署完成！访问 https://lycaonide.github.io 查看效果"

五、验证线上效果#

等待 1–3 分钟后，打开浏览器访问 https://lycaonide.github.io，刷新页面后即可看到新发布/修改的博客文章出现在文章列表中。

二、编写 camera_node.py 和 detect_node.py，在 setup.py 中注册节点#

• camera_node.py：实现等待目标检测服务、打开摄像头、读取图像帧、调用服务、显示图像的功能。

• detect_node.py：实现提供目标检测服务、接收图像请求、运行 MediaPipe 检测、返回结果的功能。

• setup.py 配置 entry_points：

  1
  entry_points={
  2
      'console_scripts': [
  3
          'camera_node = object_detect_service.camera_node:main',
  4
          'detect_node = object_detect_service.detect_node:main',
  5
      ],
  6
  },

三、安装依赖#

在终端依次执行以下命令，安装指定版本依赖库：

1
pip install "numpy<2.0"
2
pip install "opencv-python==4.10.0.84" "opencv-contrib-python==4.10.0.84"
3
pip install mediapipe

四、安装摄像头测试工具#

执行命令安装 cheese 摄像头硬件测试工具：

1
sudo apt update
2
sudo apt install cheese -y

五、编译功能包#

进入工作空间根目录，先编译消息服务包，再编译目标检测功能包：

1
cd ~/first_ws
2
colcon build --packages-select msg_srv
3
colcon build --packages-select object_detect_service

六、加载环境变量#

每次新开终端，均需执行以下命令加载编译后的环境变量：

1
source install/setup.bash

七、配置虚拟机 USB 兼容性与摄像头连接#

1
sudo chmod 777 /dev/video*

1
source install/setup.bash
2
cheese

1
source install/setup.bash
2
cheese

八、改进：修改 camera_node.py 代码适配虚拟机环境#

1
# 原代码：self.cap = cv2.VideoCapture(0)
2
# 【关键改动】添加 cv2.CAP_V4L 后端，设备号根据实际情况修改
3
self.cap = cv2.VideoCapture(0 + cv2.CAP_V4L)
4
if not self.cap.isOpened():
5
    self.get_logger().error("无法打开摄像头")
6
    return

1
# 【关键改动】自动遍历 /dev/video* 设备，配合 V4L 后端
2
import glob
3
self.cap = None
4
for dev in glob.glob("/dev/video*"):
5
    dev_id = int(dev.replace("/dev/video", ""))
6
    self.cap = cv2.VideoCapture(dev_id + cv2.CAP_V4L)
7
    if self.cap.isOpened():
8
        break
9
if not self.cap or not self.cap.isOpened():
10
    self.get_logger().error("无法打开摄像头")
11
    return

1
colcon build --packages-select object_detect_service
2
source install/setup.bash

九、解决 Qt 平台插件报错#

启动 camera_node 时出现 qt.qpa.xcb: could not connect to display 错误，可选择以下两种方式之一解决：

1
export DISPLAY=:0

1
import os
2
# 【关键改动】禁用 Qt GUI，彻底解决 display 连接问题
3
os.environ["QT_QPA_PLATFORM"] = "offscreen"

1
colcon build --packages-select object_detect_service
2
source install/setup.bash

十、节点启动顺序（关键）#

1
source install/setup.bash
2
ros2 run object_detect_service detect_node

十一、结果#

（一开始 cheese 未成功，且终端出现 select() timeout 警告；修改 USB 兼容性为 3.1 后，再次用 cheese 测试意外成功弹出画面）

• detect_node 服务后台稳定运行，camera_node 成功连接服务并打开摄像头
• 弹出 frame 窗口显示实时画面，完成「服务等待 → 图像采集 → 服务调用 → 图像显示」完整流程

1. 安装Node.js#

• 操作：
  1. 打开Node.js官网，点击对应Windows版本的安装包（如“Windows Installer (.msi) 64-bit”）；
  2. 双击安装包，勾选“Accept the terms…”，点击“Next”；
  3. 安装路径保持默认（或自定义，需记住路径），点击“Next”；
  4. 勾选“Add to PATH”（自动配置环境变量），点击“Next”→“Install”→“Finish”。
• 验证： 右键桌面→选择“Git Bash Here”打开终端，输入node -v，我安装的是v.24.5.0版本。

2. 安装Git#

• 操作：

  1. 打开Git官网，点击“Download for Windows”；
  2. 双击安装包，依次点击“Next”；
  3. 安装路径保持默认，点击“Next”；
  4. 组件选择默认（需包含“Git Bash Here”），点击“Next”；
  5. 开始菜单文件夹保持默认，点击“Next”；
  6. 选择“Use Visual Studio Code as Git’s default editor”（或默认编辑器），点击“Next”；
  7. 选择“Let Git decide”（换行符处理），点击“Next”→“Next”→“Next”；
  8. 选择“Use Windows’ default console window”，点击“Next”→“Install”→“Finish”。

• 验证： 右键桌面→选择“Git Bash Here”，输入git -v，若显示版本号（如git version 2.43.0.windows.1）则成功。

• 必做配置： 在Git Bash中输入以下命令，绑定Git与GitHub的身份：

  1
  git config --global user.name "你的GitHub用户名"  # 如"lycaonide"
  2
  git config --global user.email "你的GitHub注册邮箱"

3. 注册并登录GitHub#

• 操作：
  1. 打开GitHub官网，点击“Sign up”；
  2. 输入邮箱→创建密码→输入用户名（需记住，后续仓库名要用）→完成验证；
  3. 登录后，进入GitHub主页。

二、初始化Hexo博客（本地可预览）#

三、创建GitHub Pages专属仓库#

• 操作：
  1. 登录GitHub后，点击页面右上角“+”图标→选择“New repository”；
  2. 在“Repository name”输入框中，必须填写：你的GitHub用户名.github.io（例如你的用户名为lycaonide，则填写lycaonide.github.io）；
  3. “Visibility”选择“Public”（GitHub Pages仅支持公开仓库，若为付费用户可选Private）；
  4. 不要勾选“Add a README file”“Add .gitignore”等选项（Hexo会自动生成文件）；
  5. 点击页面最下方的“Create repository”按钮。
• 验证： 仓库创建后，页面顶部会显示仓库名lycaonide.github.io，且代码区域为空（后续部署会自动上传文件）。

四、配置Hexo的部署信息（关联本地与GitHub）#

五、配置SSH密钥（解决GitHub访问权限问题）#

• 操作：

  1. 在Git Bash的my-hexo-blog目录下，输入命令生成SSH密钥（替换为你的GitHub邮箱）：

     1
     ssh-keygen -t ed25519 -C "你的GitHub注册邮箱"

     （连续按3次回车，使用默认路径和空密码）
  2. 输入命令复制密钥内容：

     1
     cat ~/.ssh/id_ed25519.pub

     （终端会显示一长串以“ssh-ed25519”开头、你的邮箱结尾的字符串，全选复制）
  3. 登录GitHub→点击页面右上角“头像”→选择“Settings”；
  4. 左侧菜单选择“SSH and GPG keys”→点击“New SSH key”；
  5. “Title”填写自定义名称（如“我的Windows电脑”），“Key”粘贴刚才复制的密钥字符串；
  6. 点击“Add SSH key”。

• 验证： 在Git Bash中输入：

  1
  ssh -T git@github.com

  终端显示“Hi lycaonide! You’ve successfully authenticated…”即密钥配置成功。

六、安装Hexo部署插件#

• 操作： 在Git Bash的my-hexo-blog目录下，输入：

  1
  npm install hexo-deployer-git --save

• 验证： 查看项目目录下的node_modules文件夹，若存在hexo-deployer-git文件夹则安装成功。

七、执行博客部署#

• 操作1：清理本地缓存 在Git Bash中输入：

  1
  hexo clean

  （终端显示“INFO Deleted database.”“INFO Deleted public folder.”即清理完成）

• 操作2：生成静态文件 输入：

  1
  hexo generate  # 可简写为 hexo g

  （终端显示“INFO Generated: xxx.html”等信息，项目目录会生成public文件夹，里面是博客的静态文件）

• 操作3：部署到GitHub 输入：

  1
  hexo deploy  # 可简写为 hexo d

• 反馈： 终端显示“INFO Deploy done: git”，且中间会显示Git推送记录（如“To github.com/lycaonide.github.io.git”）。

八、验证部署结果（确认博客在线）#

1. 查看GitHub仓库文件： 进入lycaonide.github.io仓库页面，代码区域会显示public文件夹中的文件（如index.html、css文件夹），说明文件已成功上传。

2. 访问博客网址： 打开浏览器，输入https://lycaonide.github.io（注意：需等待1-3分钟，GitHub Pages需要同步文件），若显示与本地预览一致的博客页面，则部署成功。

3. 若页面无法访问： 进入仓库→点击“Settings”→左侧选择“Pages”→确认“Source”选择的是main分支 + /(root)目录，若显示“Your site is published at https://lycaonide.github.io”则状态正常，重新等待同步即可。

九、博客发布步骤#

1
---
2
title: 我的第一篇Hexo博客  # 博客标题（会显示在页面顶部）
3
date: 2026-01-25 10:00:00  # 发布日期（自动生成，可修改）
4
tags: [Hexo, 博客]  # 文章标签（多个标签用数组包裹）
5
categories: 技术笔记  # 文章分类（可自定义分类名）
6
---

1
# 一级标题
2
这是我的第一篇Hexo博客，终于成功部署啦！
3

4
## 二级标题：Hexo的优点
5
- 轻量化，部署简单
6
- 支持Markdown编辑，写作体验好
7
- 可自定义主题（后续会分享主题更换方法）
8

9
### 三级标题：插入图片
10
把图片放到Hexo项目的`source/images/`目录下，引用方式：
11
![示例图片](/images/我的图片.jpg)  # 路径从public目录根开始
12

13
### 三级标题：添加链接
14
推荐Hexo官网：[Hexo官方文档](https://hexo.io/zh-cn/docs/)

二、Git Bash配置Conda环境（统一终端+激活环境）#

提示：所有后续操作（安装依赖、下载资源、执行脚本）均需在worldmem环境中进行，Git Bash默认不支持Conda激活，必须先配置，否则依赖安装、命令执行都会失效。

1. 配置Git Bash加载Conda脚本：
   • 右键项目文件夹（worldmem-video-demo\WorldMem）→「Git Bash Here」，打开Git Bash终端；
   • 执行以下命令创建并编辑配置文件：

     1
     touch ~/.bashrc  # 创建Conda配置文件
     2
     nano ~/.bashrc    # 打开编辑器

   • 在编辑器中粘贴以下内容（Conda脚本默认路径，若Anaconda安装路径修改需对应调整）：

     1
     source /c/Users/13062/anaconda3/etc/profile.d/conda.sh

   • 保存退出：按Ctrl+O→回车确认文件名→按Ctrl+X退出编辑器。
2. 生效配置并激活worldmem环境：
   • 执行以下命令加载配置：

     1
     source ~/.bashrc

   • 激活worldmem环境（终端开头显示(worldmem)即成功）：

     1
     conda activate worldmem

   • 验证环境：执行python --version，输出Python 3.10.x（与创建环境时指定版本一致），说明环境配置完成。

三、项目依赖安装（Conda环境内统一执行）#

前置条件：已在Git Bash中激活worldmem环境，所有依赖均安装在该环境内，不影响系统Python。

1. 切换到项目根目录：

   1
   cd /c/Users/13062/Desktop/worldmem-video-demo/WorldMem

2. 安装项目依赖：

   • 先安装requirements.txt（若项目包含该文件，一次性安装基础依赖）：

   1
   pip install -r requirements.txt

   • 按报错补充缺失依赖（运行项目时若提示「ModuleNotFoundError」，逐个安装以下核心依赖）：

     1
     pip install hydra-core lpips gradio wandb  # 核心功能依赖
     2
     pip install torchvision pillow numpy scipy opencv-python  # 数据处理依赖

3. 验证依赖安装：执行pip list | grep gradio（或其他依赖名），能看到对应版本即安装成功。

四、本地资源准备+代码修改#

1
# 1. 创建案例文件目录（项目根目录下）
2
mkdir -p assets/examples && cd assets/examples
3
# 2. 镜像站下载
4
wget https://hf-mirror.com/yslan/worldmem/resolve/main/assets/examples/case1.npz
5
wget https://hf-mirror.com/yslan/worldmem/resolve/main/assets/examples/case2.npz
6
wget https://hf-mirror.com/yslan/worldmem/resolve/main/assets/examples/case3.npz
7
wget https://hf-mirror.com/yslan/worldmem/resolve/main/assets/examples/case4.npz

1
import os
2
import requests
3
def download_assets_if_needed():
4
    asset_dir = "assets/examples"
5
    os.makedirs(asset_dir, exist_ok=True)
6
    cases = ["case1.npz", "case2.npz", "case3.npz", "case4.npz"]
7
    for case in cases:
8
        local_path = os.path.join(asset_dir, case)
9
        if os.path.exists(local_path):
10
            print(f"✅ 本地已找到 {case}，跳过下载")
11
            continue
12
        # 注释原下载逻辑（已手动下载，避免超时）
13
        # url = f"https://huggingface.co/spaces/yslan/worldmem/resolve/main/assets/examples/{case}"
14
        # resp = requests.get(url, timeout=30)
15
        # with open(local_path, "wb") as f:
16
        #     f.write(resp.content)

1
# 1. 回到项目根目录，创建权重目录
2
cd /c/Users/13062/Desktop/worldmem-video-demo/WorldMem
3
mkdir -p assets/checkpoints && cd assets/checkpoints
4
# 2. 镜像站下载权重文件
5
wget https://hf-mirror.com/zeqixiao/worldmem_checkpoints/resolve/main/diffusion_only.ckpt
6
wget https://hf-mirror.com/zeqixiao/worldmem_checkpoints/resolve/main/vae_only.ckpt
7
wget https://hf-mirror.com/zeqixiao/worldmem_checkpoints/resolve/main/pose_prediction_model_only.ckpt

1
diffusion_path: assets/checkpoints/diffusion_only.ckpt
2
vae_path: assets/checkpoints/vae_only.ckpt
3
pose_prediction_path: assets/checkpoints/pose_prediction_model_only.ckpt

五、首次启动app.py（界面成功，视频生成功能缺失）#

1. 启动命令（Git Bash中，已激活worldmem环境，项目根目录下）：

   1
   python app.py

2. 运行现象：
   • 终端日志正常输出「✅ 本地已找到 case1.npz」「🚀 初始化设备: cuda」「✅ 所有模型切换到eval模式」；
   • 浏览器自动弹出http://127.0.0.1:7860，成功进入Gradio界面，可选择场景、输入动作序列；
   • 点击「🎬 Generate!」按钮后，界面卡住无视频输出，终端无额外日志（无报错）。
3. 产生问题原因：视频生成依赖ffmpeg工具进行帧序列转MP4格式，本地未安装ffmpeg，项目无法调用该工具，导致视频生成功能加载失败。
4. 关闭项目：按Ctrl+C终止终端进程，关闭浏览器。

六、ffmpeg下载与安装配置（补全视频生成依赖）#

七、重新启动app.py（视频生成加载成功，内存不足失败）#

1. 启动命令（新打开的Git Bash中，项目根目录下）：

   1
   python app.py

2. 运行现象：
   • 终端日志正常初始化，视频生成组件加载成功（终端显示「ffmpeg相关初始化日志」）；
   • 加载diffusion_model权重（3605MB）时，终端卡住，随后输出「Segmentation fault」，进程终止；
   • 任务管理器显示：CPU内存占用飙升至15.0GB+（总物理内存15.22GB），剩余可用内存不足200MB，触发内存溢出。
3. 问题原因：ffmpeg安装后，视频生成组件初始化增加了内存占用，叠加3.6GB的模型权重加载，16GB物理内存不足以承载，导致段错误。

八、训练脚本执行#

1. 补充训练依赖（若之前未安装）：

   1
   pip install wandb  # 训练日志监控依赖

2. 修复训练脚本配置：打开项目根目录下train_stage_1.sh文件，将algorithm.metrics=[lpips,psnr]改为+algorithm.metrics=[lpips,psnr]（适配Hydra配置语法，避免报错）。
3. 执行训练脚本（Git Bash中，项目根目录下）：

   1
   sh train_stage_1.sh

   （注：若内存充足，脚本会正常启动训练；若内存不足，会出现与启动app.py类似的内存溢出报错）

九、Git Bash环境常用命令速查表#

十、核心问题与解决方案汇总（按遇到顺序排列）#

十一、项目核心用途总结#

WorldMem 是一个「基于动作交互的3D世界模拟与长视频生成工具」，核心价值是解决“单张场景图→上下文连贯长视频”的创作痛点，具体功能与场景如下：

1. 核心功能：
   • 6种预设场景（向日葵平原、沙漠、冰原等），支持任意场景作为初始帧；
   • 动作交互（W/A/S/D/Q/E等按键组合），可实现转向、移动、使用物品等操作；
   • 长视频生成：连续点击「Generate」扩展视频长度，自动维护场景3D结构、物体位置的一致性（新帧用红框标记）；
   • 模型训练：通过train_stage_1.sh脚本训练自定义模型，优化生成效果。
2. 应用场景：
   • 游戏开发：快速生成开放世界视频片段，无需手动建模动画；
   • 虚拟模拟：基于简单指令模拟虚拟环境视角移动与交互；
   • 内容创作：为动画、影视领域提供低成本场景扩展工具。

关键注意事项#

1. 流程逻辑优先级：必须先配置Git Bash的Conda环境，再安装依赖、下载资源——无环境则所有依赖安装、命令执行都会失效，这是最关键的前置步骤。
2. ffmpeg安装红线：路径必须无中文、无空格，环境变量必须指向bin目录，否则视频生成功能始终加载失败。
3. 内存是核心瓶颈：16GB物理内存仅能满足基础界面启动，视频生成+模型权重加载需≥32GB物理内存，或扩展20-40GB虚拟内存。
4. 终端统一原则：全程使用Git Bash操作，避免切换Anaconda Prompt/CMD导致环境不一致，减少报错概率。
5. 资源完整性：案例文件（4个.npz）和模型权重（3个.ckpt）必须完整下载，缺失任一文件会导致项目启动失败。