Skip to content

Commit f87462e

Browse files
rockbenbenrockbenben
committed
docs
1 parent e426dd3 commit f87462e

2 files changed

Lines changed: 255 additions & 228 deletions

File tree

‎README.md‎

Lines changed: 232 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<p><strong>开源工具、效率方法、心理学探索的自我提升笔记</strong></p>
44

55
<p>
6-
<a href="https://newzone.top"><img src="https://img.shields.io/badge/📖_在线阅读-newzone.top-blue?style=for-the-badge" alt="在线阅读"></a>
6+
<a href="https://newzone.top"><img src="https://img.shields.io/badge/🌐_使用案例-newzone.top-blue?style=for-the-badge" alt="使用案例"></a>
77
<a href="https://discord.gg/PZTQfJ4GjX"><img src="https://img.shields.io/discord/1048780149899939881?color=%2385c8c8&label=Discord&logo=discord&style=for-the-badge" alt="Discord"></a>
88
</p>
99

@@ -14,8 +14,8 @@
1414
</p>
1515

1616
<p>
17-
<a href="https://t.me/aishort_top">📢 Telegram</a> ·
18-
<a href="https://qm.qq.com/q/qvephMO8q4">💬 QQ 群</a> ·
17+
<a href="https://t.me/aishort_top">📢 Telegram</a> ·
18+
<a href="https://qm.qq.com/q/qvephMO8q4">💬 QQ 群</a> ·
1919
<a href="https://github.com/rockbenben/LearnData/issues">🐛 反馈</a>
2020
</p>
2121
</div>
@@ -37,15 +37,6 @@ LearnData 基于 VuePress + vuepress-theme-hope 构建，将笔记与文章聚
3737
</tr>
3838
</table>
3939

40-
## 🚀 快速开始
41-
42-
1. 点击 [Use this template](https://github.com/rockbenben/LearnData/generate) 创建你的仓库
43-
2. 启用 GitHub Actions 的读写权限 (`Settings > Actions > General`)
44-
3. 重新运行 workflow 以部署页面
45-
4. 在 `Settings > Pages` 中设置 `gh-pages` 分支为源
46-
47-
**详细教程请访问：[LearnData 完整文档](https://newzone.top/)**
48-
4940
## 🎯 核心功能
5041

5142
| 功能 | 说明 |
@@ -59,6 +50,232 @@ LearnData 基于 VuePress + vuepress-theme-hope 构建，将笔记与文章聚
5950
| 🤖 看板娘 | Live2D Widget 增加趣味性 |
6051
| 🚀 自动部署 | GitHub Actions 一键部署到 GitHub Pages / Vercel |
6152

53+
## 🚀 快速开始（TL;DR）
54+
55+
1. 点击 [Use this template](https://github.com/rockbenben/LearnData/generate) 创建你的仓库
56+
2. 启用 GitHub Actions 的读写权限 (`Settings > Actions > General`)
57+
3. 重新运行 workflow 触发部署
58+
4. 在 `Settings > Pages` 中设置 `gh-pages` 分支为源
59+
60+
详细图文步骤、配置项、部署方式与常见错误处理见下面各节。
61+
62+
---
63+
64+
## 🍥 详细搭建步骤
65+
66+
按以下六步完成 LearnData 的初次搭建。整个流程不需要本地环境，全部在 GitHub 网页上完成。
67+
68+
### 1. 用模板创建你的仓库
69+
70+
访问 [LearnData 项目页面](https://github.com/rockbenben/LearnData)，点击页面右上角的「Use this template」按钮，在弹出的页面中选择「Create a new repository」以创建一个基于此模板的新仓库。
71+
72+
![](https://img.newzone.top/2022-08-10-19-32-05.png?imageMogr2/format/webp)
73+
74+
![](https://img.newzone.top/2022-08-10-19-34-13.png?imageMogr2/thumbnail/500x)
75+
76+
### 2. 开放 Workflow 写权限
77+
78+
进入你的项目仓库，点击「Settings」>「Actions」>「General」，找到页面底部的 `Workflow permissions` 设置。选中 `Read and write permissions` 选项，点击保存。这一步确保 GitHub Page 在部署时能正确访问和修改你的仓库内容，避免因权限不足导致部署失败（报错 `failed with exit code 128`）。
79+
80+
![](https://img.newzone.top/2023-03-14-04-02-16.png?imageMogr2/format/webp)
81+
82+
### 3. 触发首次部署
83+
84+
进入菜单栏顶部的「Actions」页签，选择最新的 workflow。在页面右上方点击「Re-run jobs」>「Re-run all jobs」，触发 GitHub 重新生成并部署网页。如果设置无误，GitHub 会自动创建一个名为 `gh-pages` 的分支，并在其中部署你的页面。
85+
86+
![](https://img.newzone.top/2023-03-14-04-04-52.gif?imageMogr2/format/webp)
87+
88+
### 4. 修改仓库名为用户主页
89+
90+
返回「Settings」页面，修改 `Repository name` 为 `你的用户名.github.io`。例如，如果你的仓库链接是 `https://github.com/xxx/LearnData`，那么 `xxx` 就是你的 GitHub 用户名。若该名称已被其他项目使用，系统会显示红色错误提示。
91+
92+
此时，你可以选择任意其他名称，例如 `LearnData`，部署页面路径将变为 `你的用户名.github.io/LearnData`。如果页面样式显示不正常，可能需要设置子域名，参考 [常见问题 - 网页显示异常](#网页显示异常)。
93+
94+
![](https://img.newzone.top/20180505202201.png?imageMogr2/format/webp)
95+
96+
### 5. 设置 Pages 构建分支
97+
98+
在「Settings」>「Pages」>「Build and deployment」>「Branch」中，将 `gh-pages` 分支设置为 GitHub Pages 的源。大部分情况下，网站运行目录保持默认的 `/(root)` 即可。完成设置后，点击「Save」保存。
99+
100+
如果在此步骤中未找到 `gh-pages` 分支，请回到第三步重新触发一次 workflow。
101+
102+
![](https://img.newzone.top/2022-08-10-19-39-15.png?imageMogr2/format/webp)
103+
104+
### 6. 访问站点
105+
106+
设置完成后，稍等几分钟再刷新页面，你将看到一个新的访问链接提示：`https://你的用户名.github.io/`。此时你的个人知识库已经成功搭建。
107+
108+
### 本地运行
109+
110+
如需在本地预览或修改：
111+
112+
1. 安装 npm 和 pnpm 环境（参考 [VPS 环境部署](https://newzone.top/deploy/vps/#环境部署)）
113+
2. 在项目目录下运行 `pnpm i` 安装依赖
114+
3. 运行 `pnpm docs:dev`，访问 `http://localhost:8080/`
115+
116+
---
117+
118+
## 🔣 配置 LearnData
119+
120+
### 文档结构
121+
122+
文章和页面的配置可参考主目录下的 [samplepage.md](https://github.com/rockbenben/LearnData/blob/main/samplepage.md?plain=1)。其中 `order` 参数表示侧边栏的顺序，数字越小越靠前，支持非整数和负数。
123+
124+
我个人的偏好是：非干货短文 `order` 设在 -0.01 到 -0.99；干货长文设在 -1 到负无穷。每次新增文章在上一篇基础上递减 `order` 值。这种设置使我能随时记录低于 1000 字的短文，不影响干货文章的置顶排序。
125+
126+
`src` 目录结构：
127+
128+
```bash
129+
src
130+
|── .vuepress # 网站配置
131+
│ ├── config.ts # 网站环境依赖和网站属性
132+
│ ├── sidebar.ts # 侧边栏
133+
│ ├── navbar.ts # 导航栏
134+
│ ├── theme.ts # 主题和插件
135+
│ └── templateBuild.html # 网页模板，网站关键词和统计
136+
|── _posts # 博客文章目录
137+
├── _temp # 草稿箱
138+
├── reading # 读书笔记
139+
├── encrypt # 加密目录（可指定其他目录）
140+
├── anyname # 自定义笔记
141+
├── blog.md # 博客页面
142+
└── intro.md # 博主个人介绍
143+
```
144+
145+
`src/.vuepress` 路径下是网站的配置文件，已添加详细注释。可参考 [vuepress-theme-hope 配置案例](https://github.com/vuepress-theme-hope/vuepress-theme-hope/tree/main/docs/theme/src/.vuepress) 调整。在 `src/.vuepress/sidebar.ts` 中修改文件夹路径，后台会自动抓取路径下的 md 文件生成侧边栏。`src/.vuepress/theme.ts` 包含[评论插件](https://newzone.top/web/Comments.html)的相关配置。
146+
147+
注意事项：
148+
149+
- LearnData 默认采用 Algolia 全文检索。如未使用 Algolia，可在 `src/.vuepress/theme.ts` 的 plugins 部分删除 docsearch 区块，激活 searchPro 改用本地全文索引
150+
- `src/_temp` 文件夹默认不同步到 GitHub，可手动在本地建立 `_temp` 文件夹存放草稿
151+
- 自 VuePress 2 的 beta.54 版本起，文件夹名前缀 `_` 在生成链接时会被省略（如文章路径 `/_posts/` 编译为 `/posts/`）
152+
153+
### 看板娘
154+
155+
LearnData 集成了看板娘 [Live2D Widget](https://github.com/stevenjoezhang/live2d-widget)，支持随机对话、切换人物服饰和打飞机游戏。如不需要，可删除 `src/.vuepress/public/live2d-widget` 文件夹。
156+
157+
如果网站部署在子页面（例如 `https://xxx.github.io/yyy`），需要将子页面路径 `yyy` 加入到以下两个文件：
158+
159+
- 将 `src/.vuepress/public/live2d-widget/autoload.js` 第三行的 `const live2d_path = "/live2d-widget/"` 修改为 `const live2d_path = "/yyy/live2d-widget/"`
160+
- 将 `src/.vuepress/templateBuild.html` 中看板娘区块的 `<script src="/live2d-widget/autoload.js">` 修改为 `<script src="/yyy/live2d-widget/autoload.js">`
161+
162+
如需调整模型，参照 `src/.vuepress/public/live2d-widget` 目录下的 README。若在服务器上自建 [live2d api](https://github.com/fghrsh/live2d_api)，请添加跨域配置避免仅显示文本而无图片。或使用 CDN：把 `cdnPath: live2d_path + "live2d_api/"` 改为 `cdnPath: "https://live2d-api.aishort.top/"`。
163+
164+
### 读书笔记
165+
166+
读书笔记中常含大量原文引用，与 LearnData 精简化的初衷不符。我们用 Docsify 构建读书笔记，与 LearnData 主站互不干扰，形成两个独立的搜索系统。
167+
168+
- **读书目录**：读书笔记存放在 `src/reading` 下。该路径不会被转换为 HTML，而是自动复制到静态站点下，完成 Docsify 页面构建和独立搜索索引
169+
- **修改链接域名**：Docsify 不支持相对链接。在 `src/.vuepress/sidebar.ts` 中将 `{ text: "读书笔记", icon: "read", link: "https://newzone.top/reading/" }` 的 `newzone.top` 替换为你自己的域名
170+
- **移除阅读统计**：如未部署 Waline 或不需要评论功能，可移除 `src/reading/index.html` 中的 Waline 配置代码块：
171+
172+
```javascript
173+
waline: {
174+
serverURL: "https://waline.newzone.top",
175+
...
176+
}
177+
```
178+
179+
### 本地图片引用
180+
181+
为避免在生成静态页面时出现 `Rollup failed to resolve import` 错误，本地图片必须保存在 `src/.vuepress/public` 路径下。
182+
183+
如果图片名称为 `1.png`，保存在 `src/.vuepress/public/imgs` 路径下，则可以使用以下链接引用：`/imgs/1.png` 或使用 Markdown 图片链接：`![](/imgs/1.png)`。本方法也适用于将附件部署到网站上。
184+
185+
---
186+
187+
## 🖥️ 网站部署
188+
189+
GitHub 部署后，由于国内访问速度不稳定，建议增加国内访问节点。
190+
191+
很多人选择 Gitee Pages 作为国内节点，但 Gitee Pages 限制较多（必须实名认证、免费版无法自定义域名、有下架风险）。我没选择 Gitee，而是同步到国内服务器（域名需备案）或 Vercel（国外服务可能断网）。
192+
193+
### 同步到自有服务器
194+
195+
如果项目搭建好后出现红色错误，可能是 GitHub Actions 同步到服务器时发生错误。进入仓库的「Setting」>「Secrets and variables」>「Action」，添加 `FTP_HOST`、`FTP_PORT`、`FTP_USERNAME`、`FTP_PASSWORD` 密钥。文件变更时，GitHub Actions 会自动推送到服务器 FTP。
196+
197+
也可参考 [GitHub 同步到 OSS](https://newzone.top/deploy/Static.html#同步到-oss) 部署到云存储。
198+
199+
### 部署到 Vercel
200+
201+
Vercel 速度比 GitHub Pages 快，但 `*.vercel.app` 域名已受 DNS 污染影响，国内用户需绑定自定义域名。
202+
203+
部署步骤：
204+
205+
1. 点击 [![Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Frockbenben%2FLearnData%2Ftree%2Fgh-pages) 或将 `https://vercel.com/new/clone?repository-url=https://github.com/rockbenben/LearnData/tree/gh-pages` 中的 `rockbenben/LearnData` 改为 `你的用户名/仓库名`。建议使用 GitHub 账户登录。
206+
207+
2. 输入 Vercel 项目名称，默认 private，点击 `Create`。
208+
209+
![](https://img.newzone.top/2022-08-24-17-24-16.png?imageMogr2/format/webp "创建 Vercel 项目")
210+
211+
3. Vercel 会基于 LearnData 模板新建并初始化仓库。几十秒后部署成功，点击 `Go to Dashboard` 跳转到控制台。
212+
213+
![](https://img.newzone.top/2022-08-24-17-21-58.png?imageMogr2/format/webp "Vercel 部署成功")
214+
215+
4. 当前 Vercel 页面仅用于演示，不会随项目自动更新。依次选择「Project Settings」>「Git」>「Connected Git Repository」，点击「Disconnect」，然后点击 GitHub 图标，选择第一步中的「你的用户名/仓库名」，点击 `Connect`。
216+
217+
![](https://img.newzone.top/2024-08-22-14-05-07.png?imageMogr2/format/webp "移除演示项目")
218+
219+
![](https://img.newzone.top/2024-08-22-14-07-13.png?imageMogr2/format/webp "链接同步项目")
220+
221+
5. 在「Production Branch」中将分支名从 `main` 改为 `gh-pages`。保存后页面随项目同步更新。
222+
223+
![](https://img.newzone.top/2024-08-22-14-09-31.png?imageMogr2/format/webp "切换 Vercel 分支")
224+
225+
如部署遇错，请检查 Vercel 项目的 `Node.js Version` 是否设置为 `20.x`。
226+
227+
---
228+
229+
## 🤔 常见问题
230+
231+
### 网页显示异常
232+
233+
如果你的网站仅显示文本而不正常加载样式和脚本，可能是网站路径设置错误。这通常发生在将仓库作为子路径部署时，例如 `https://xxx.github.io/LearnData/`。
234+
235+
![](https://img.newzone.top/2023-03-14-06-11-10.png?imageMogr2/format/webp)
236+
237+
解决步骤：
238+
239+
1. 在你的项目中打开 `src/.vuepress/config.ts`
240+
2. 将 `base` 配置项改为你的子路径 `/LearnData/`：
241+
242+
```typescript
243+
export default defineUserConfig({
244+
base: "/LearnData/",
245+
// 其他配置...
246+
});
247+
```
248+
249+
3. 提交并推送更改，等待 GitHub Actions 自动重新部署
250+
4. 部署后，刷新网站应能正常显示
251+
252+
如果你的网站部署在根路径（如 `https://xxx.github.io/`），`base` 应保留默认值 `/`。
253+
254+
### 同步服务器常见错误
255+
256+
GitHub Actions 自动部署到服务器时常见错误：
257+
258+
- **`Error: Input required and not supplied: server`** —— 服务器参数未配置。检查 `.github/workflows/main.yml` 的相关配置。如不需要同步到服务器，可直接删除 `Sync files` 区块
259+
- **`FTPError: 530 Login authentication failed`** —— FTP 登录认证失败，账号/密码错误。建议用 FileZilla 等客户端测试账号有效性
260+
- **`Error: Timeout (control socket)`** —— 服务器连接超时。可在 GitHub Actions 页面点「Re-run all jobs」重试。多次失败时检查服务器防火墙、GitHub IP 是否被屏蔽
261+
- **`Error: Can't open data connection in passive mode: connect ETIMEDOUT ***:39005`** —— FTP 被动模式连接失败，常见原因：
262+
1. **防火墙未开放被动端口范围**（如 39000–40000）
263+
2. **返回了错误的 IP 地址**：FTP 服务器返回内网 IP。可在配置文件（如 `pure-ftpd.conf`）取消注释 `ForcePassiveIP`，设置为公网 IP
264+
3. **连接空闲超时**：FTP 会话超过 `MaxIdleTime`（默认 15 分钟）被断开，可调高该参数
265+
4. **连接数限制**：CI/CD 短时间内多次连接触发保护，可调高 `MaxClientsPerIP` 和 `PerUserMaxConnections`（如设为 50），重启 FTP 服务
266+
267+
### Get counter failed with 403
268+
269+
`Get counter failed with 403` 错误仅在本地 `pnpm docs:dev` 时使用**非 localhost 域名**会发生，静态构建过程中不出现。这是 Waline 评论插件引起的。在 `src/.vuepress/theme.ts` 的 plugins 部分删除 Waline 配置即可。
270+
271+
![](https://img.newzone.top/2024-02-23-21-07-05.png?imageMogr2/format/webp)
272+
273+
### ERR_MODULE_NOT_FOUND
274+
275+
如出现 `Error [ERR_MODULE_NOT_FOUND]: Cannot find module` 报错，可能是第三方插件或 `package.json` 依赖未正确配置。可使用最新版本的 `package.json` 和 `pnpm-lock.yaml` 覆盖本地设置，或删除主目录下的 `.npmrc` 文件。
276+
277+
---
278+
62279
## 📁 项目结构
63280

64281
```
@@ -71,14 +288,14 @@ src/
71288

72289
## 📚 相关资源
73290

74-
- **完整文档**：[newzone.top](https://newzone.top/)
75-
- **进阶技巧**：[知识管理与搜索](https://newzone.top/posts/2024-01-28-learndata-advanced.html) · [自动化脚本](https://newzone.top/posts/2026-03-05-learndata-scripts-llm-seo.html)
291+
- **真实使用案例**：[newzone.top](https://newzone.top/) —— 博主基于本模板搭建的博客
292+
- **进阶心得**：[知识管理与搜索](https://newzone.top/posts/2024-01-28-learndata-advanced.html) · [自动化脚本](https://newzone.top/posts/2026-03-05-learndata-scripts-llm-seo.html)
76293
- **问题反馈**：[GitHub Issues](https://github.com/rockbenben/LearnData/issues)
77294
- **交流社区**：[Discord](https://discord.gg/PZTQfJ4GjX) · [Telegram](https://t.me/aishort_top) · [QQ 群](https://qm.qq.com/q/qvephMO8q4)
78295

79296
## 🆙 版本升级
80297

81-
升级时，仅需更新项目根目录文件（除 `src` 外），并比对 `src/.vuepress/config.ts` 和 `theme.ts` 的变更。
298+
升级时仅需更新项目根目录文件（除 `src` 外），并比对 `src/.vuepress/config.ts` 和 `theme.ts` 的变更。
82299

83300
详见 [CHANGELOG.md](./CHANGELOG.md)
84301

0 commit comments

Comments
 (0)