Pure Studio 使用与开发文档
Pure Studio 的安装、工作区、文章编辑、站点配置、素材库、Git、终端与构建发布说明。
Pure Studio 是一个面向 Astro Pure 博客的本地桌面工作台。它把文章、文档、Markdown 编辑、素材管理、站点配置、Git 和终端收在同一个窗口里,数据始终保存在本地博客工程中。
项目仓库:github.com/zeionl84/astro-pure-studio ↗
如果你更想先了解它为什么这样设计,可以阅读博客文章《从重复劳动到工作台:Pure Studio 的探索路程》。
适合谁#
- 使用 Astro Pure 搭建个人博客,希望减少手工改文件的人。
- 已经熟悉 Markdown 和 Git,但不想在发布前反复切换多个窗口的人。
- 想阅读或二次开发一个 Tauri 2 + Vue 3 桌面项目的人。
它不替代完整的 IDE,也不负责自动部署、数据库或云端后台。
设计背景与取舍#
Pure Studio 最初只是一个文章管理器。真正推动它继续扩展的,是发布前那些重复动作:改站点信息、找素材、检查 Git、跑构建、看终端输出。每加一个功能,都会先问一个问题:它是否真的减少了切换窗口的次数?
这个探索过程形成了几个取舍:
- 本地优先:内容以工作区里的 Markdown 和源码文件为准,不引入云端数据库。
- 不重新发明 Git:界面只做状态、暂存、提交和同步,复杂历史操作交还给 Git。
- 终端使用现有生态:前端用 xterm.js,后端用 PTY,而不是继续维护一个只能跑单条命令的输入框。
- 边界清晰:Git、终端和站点配置都只操作工作区内的路径,内部状态尽量放在
.pure-studio/。 - 先可用,再完整:没有图片压缩、分支切换和自动部署,但日常写作与发布路径已经能走通。
完整的探索故事、踩坑记录和设计取舍写在博客《从重复劳动到工作台:Pure Studio 的探索路程》里。
环境要求#
| 依赖 | 要求 |
|---|---|
| 操作系统 | Windows 10 / 11 |
| Node.js | >= 20 |
| Rust | stable,包含 cargo 和 rustc |
| Tauri CLI | 2.x,确保 cargo tauri 可用 |
| WebView2 | Windows 需要安装运行时 |
检查环境:
node --version
rustc --version
cargo tauri --version
git --versionpowershell没有 Tauri CLI 时可以先安装:
cargo install tauri-clipowershell获取与启动#
git clone https://github.com/zeionl84/astro-pure-studio.git
cd astro-pure-studio
npm install
npm run tauri:devpowershell开发模式会先构建一次前端,然后在 http://127.0.0.1:1420 提供静态资源,并在 src/ 变化时自动重建。
如果只想调试界面,可以拆成两个终端:
# 终端一:只启动前端开发服务
npm run dev
# 终端二:启动 Tauri 桌面壳
cargo tauri devpowershell打开博客工作区#
首次启动会出现工作区选择页。选择博客根目录即可,例如:
C:\Users\you\myproject\radiant-masstextStudio 会自动识别 src/content/blog、src/content/docs 和 site.config.ts,并读取文章、文档、媒体与站点信息。
支持的情况:
- 标准 Astro Pure 工程。
- 内容目录使用
src/content/posts或自定义src/content结构。 - 已存在
.pure-studio/配置目录的工程(不会重复覆盖)。
如果目录不是 Astro 工程,界面会提示缺少项目配置,而不是直接写入文件。
主要内容功能#
文章与文档#
在「文章」或「文档」中:
- 新建、编辑、重命名和删除内容。
- 用 frontmatter 表单编辑标题、摘要、日期、标签、语言、头图、草稿和置顶。
- 使用 Markdown 工具栏插入标题、列表、引用、代码块、表格、链接和图片。
- 实时预览标题、表格、代码块和任务列表。
- 删除内容会先进入工作区的回收站,不直接销毁文件。
保存时会保留未知的 frontmatter 字段,避免内容在表单往返中被悄悄丢掉。
编辑器与预览#
编辑器提供常用 Markdown 操作,预览区支持:
- 标题锚点与目录。
- 代码块和轻量语法高亮。
- 链接、图片和任务列表。
- 预览中的外链可以用系统浏览器打开。
预览是项目内的轻量渲染器,不执行 MDX 组件,也不解析脚注和数学公式。需要完整 Astro 渲染时,请运行博客自己的构建。
素材库#
素材库扫描站点素材目录和文章目录,支持:
- 图片:
png、jpg、jpeg、webp、gif、avif、svg、bmp、ico、tif、tiff - 视频:
mp4、webm、mov、m4v、ogv - 音频:
mp3、wav、ogg、m4a、flac、aac - 文档:
pdf、txt、json - 字体:
woff、woff2、ttf、otf
可以按类型筛选、预览图片/视频/音频、复制路径,或在文章编辑器中选择站点内的图片作为头图和插图。
素材复制到文章目录时,会使用相对于文章的路径,避免把绝对路径带进 Markdown。
站点信息、页脚与二维码#
「站点设置 → 站点信息」可以编辑:
- 站点标题、作者、描述、个性签名。
- 界面语言、Favicon、社交分享图、头像 Logo。
- 社交链接列表:图标、名称、链接,最多 8 条。
同一页的「页脚、版权与二维码」可以编辑:
- 页脚版权前缀。
- 是否显示主题署名。
- 版权协议名称和链接。
- 文章底部版权声明。
- 二维码开关、标题、说明和内容/目标。
二维码默认指向当前文章链接,也可以改成任意文本或 URL。二维码在构建时本地生成,不依赖外部 CDN。
保存后,Studio 会更新 src/pure-studio.config.ts、site.config.ts 中的相关字段,并写入 src/site-content.ts。请在保存后检查 Git diff,确认符合预期。
Git 版本控制#
「版本控制」提供日常发布所需的最小集合:
- 当前分支、上游、领先/落后提交。
- 已暂存、未暂存、未跟踪文件。
- 逐文件暂存、取消暂存、全部暂存。
- 提交说明与提交到本地仓库。
pull --ff-only和普通push。- 初始化 Git 仓库。
Git 依赖本机命令行 git,不内置 Git 运行时,也不保存远程凭据。分支切换、冲突合并和重置不在当前界面内,请使用你熟悉的 Git 客户端。
每次提交前建议:
- 在 Git 页确认改动文件。
- 阅读一两次 diff(可以在编辑器或外部 Git 客户端)。
- 写清楚提交说明再提交。
终端与全局日志#
「终端与日志」使用 xterm.js 和本地 PTY,在博客根目录启动:
- Windows 默认 PowerShell。
- 其他平台使用
$SHELL,回退到sh。 - 支持交互输入、
Ctrl+C、复制、粘贴、清屏、自适应窗口大小和重新连接。
日志是全局的,保存在应用配置目录的 logs/terminal.log,不随工作区切换清空。每次打开终端都会追加一个会话块,包含时间、工作区和 Shell 名称。
常用命令:
bun run build
npm run build
git status
git log --oneline -20powershell终端以当前用户权限运行,没有内置沙箱。只执行你信任的命令。
配置与文件边界#
Studio 主要写入以下位置:
| 路径 | 用途 |
|---|---|
site.config.ts | 站点基础信息、菜单、页脚社交链接 |
src/pure-studio.config.ts | Studio 生成的主题配置覆盖 |
src/site-content.ts | 页脚、版权、二维码等文本内容 |
.pure-studio/site.json | Studio 自己的站点状态快照 |
.pure-studio/disabled-pages/ | 被禁用的主题页面目录 |
应用配置目录的 logs/ | 全局终端日志与临时数据 |
建议把 .pure-studio/ 加入博客仓库的 .gitignore,除非你希望和团队共享这些本地状态。
构建与测试#
在 Studio 工程内:
npm run check # 类型检查 + Rollup 构建 + SSR 冒烟测试
npm run typecheck # 仅类型检查
npm run build # 仅构建 dist/
npm run smoke # 离线渲染主要界面powershellRust 测试:
cd src-tauri
cargo testpowershellnpm run check 不需要启动 Tauri 或 WebView2,适合在 CI 或受限环境中先验证前端与视图。
打包桌面应用#
npm run tauri:buildpowershell如果没有 NSIS 工具链,可以只生成可执行文件:
npm run build
cargo build --release --offline --features custom-protocol --manifest-path src-tauri/Cargo.tomlpowershell--offline 依赖本地 Cargo 缓存;首次构建或缓存不完整时去掉该参数。
常见问题#
启动后显示 Not found#
开发模式下如果前端构建尚未完成,静态服务可能暂时找不到页面。等待构建结束再刷新。如果持续出现,检查 npm run dev 的终端输出是否有编译错误。
终端无法输入#
先点击终端区域,确保焦点在 xterm 的文本输入层。自动化工具需要注意:程序化点击 .xterm-screen 不一定能让 xterm 获得焦点,应该显式聚焦 .xterm-helper-textarea。
Git 操作失败#
确认本机 git --version 可用,工作区本身是一个 Git 仓库,并且当前用户对 .git 有写权限。凭据、代理和 SSH 配置由本机 Git 管理,Studio 不会代为输入密码。
二维码不显示#
确认「文章二维码」开关已打开。二维码默认使用当前文章链接;如果填写了自定义目标,请检查目标是否为空或格式是否合法。
保存后构建失败#
先查看 Git diff 和终端构建日志。常见原因是手写的 site.config.ts 或 site-content.ts 语法错误,或者新增 frontmatter 字段不符合 Astro schema。Studio 会尽量保留未知字段,但不会替代 Astro 的 schema 校验。
开发说明#
主要目录:
src/
components/ 复用的界面与编辑器组件
core/ API、类型、Markdown 渲染和工具函数
state/ 应用状态与动作
views/ 各功能页面
src-tauri/src/
commands.rs Tauri 命令入口
site.rs 站点配置与内容读写
media.rs 素材扫描、导入与协议
git.rs Git 状态与操作
terminal.rs PTY 会话与全局日志
workspace.rs 工作区探测
tools/ 自定义 Rollup 构建、SSR 冒烟测试与开发服务text提交前建议至少运行:
npm run check
cd src-tauri
cargo testpowershell许可证#
本项目使用 Mozilla Public License 2.0(MPL-2.0) ↗。
你可以自由使用、修改和分发;分发修改后的源文件时,需要继续以 MPL-2.0 提供相应源文件并保留许可证与版权声明。