如何写与管理笔记

先看目录结构说明，再从当前阶段页进入。目录按学习阶段、知识专题、项目和日志分开，之后找回一条记录会更容易。

启动网站

最简单的方式：双击项目根目录的 Start-Notes.cmd。保持窗口运行，浏览器即可预览笔记；关闭服务时按 Ctrl + C。

也可以在此文件夹打开 PowerShell，执行：

$env:PATH = "$env:NVM_HOME\v24.22.1;$env:PATH"
npm.cmd run docs:dev

浏览器访问终端显示的本地地址，默认是 http://127.0.0.1:5173/。

修改已有笔记

用 VS Code 打开整个“笔记文件”文件夹，进入 docs，修改对应 .md 文件并保存。预览页面会自动更新。

左侧是笔记分类，右侧是当前文章的小标题。顶部搜索可检索文章；不需要注册账号或提供 API 密钥。

新增一篇文章

例如记录 WebSocket 重连：

1. 新建 docs/learning/month-01-foundation/websocket-reconnect.md。
2. 从知识笔记模板复制结构，写入自己的理解、手写练习和排错记录。
3. 在 docs/learning/month-01-foundation/index.md 的“我的笔记索引”中加一行：

| 2026-10-27 | WebSocket 重连 | [打开笔记](./websocket-reconnect) | [ ] |

如果希望左侧固定导航也有该文章，再编辑 docs/.vitepress/config.mts，将文章加到对应阶段的 items 数组。阶段页目录即可作为常用入口，单篇新笔记不必每次都改全站侧边栏。

文件名建议使用英文、小写和连字符；页面里的标题可以直接用中文。

Markdown 常用写法

# 文章标题

## 一个知识点

普通文字，**重点加粗**，`行内代码`。

- 一条记录
- 另一条记录

- [ ] 尚未完成
- [x] 已经完成

```js
console.log('今天的手写练习')
```

学习路线里的方框通过修改 Markdown 文件记录进度：把 □ 改为 ☑。修改完成并保存后，网页会自动更新。

保存图片

把图片放进 docs/public/images 文件夹，例如 scene.png，在文章中写：

![场景截图](/images/scene.png)

少量、可公开展示的 glb 示例可以放在 docs/public/models；源模型、超大文件和隐私数据不建议直接放进笔记仓库。

备份和换电脑

备份整个“笔记文件”文件夹即可；node_modules、docs/.vitepress/cache 和 docs/.vitepress/dist 可以不备份。

新电脑安装相应版本的 Node.js，复制文件夹后执行：

npm.cmd ci
npm.cmd run docs:dev

项目已经包含 .gitignore，将来可以把源文件纳入 Git。当前未发布到远程仓库，也未配置云同步。

构建和预览

npm.cmd run docs:build
npm.cmd run docs:preview

构建产物在 docs/.vitepress/dist。先在本地使用，之后需要时再配置网站部署。