zeionl博客

返回

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
Ruststable,包含 cargo 和 rustc
Tauri CLI2.x,确保 cargo tauri 可用
WebView2Windows 需要安装运行时

检查环境:

node --version
rustc --version
cargo tauri --version
git --version
powershell

没有 Tauri CLI 时可以先安装:

cargo install tauri-cli
powershell

获取与启动#

git clone https://github.com/zeionl84/astro-pure-studio.git
cd astro-pure-studio
npm install
npm run tauri:dev
powershell

开发模式会先构建一次前端,然后在 http://127.0.0.1:1420 提供静态资源,并在 src/ 变化时自动重建。

如果只想调试界面,可以拆成两个终端:

# 终端一:只启动前端开发服务
npm run dev

# 终端二:启动 Tauri 桌面壳
cargo tauri dev
powershell

打开博客工作区#

首次启动会出现工作区选择页。选择博客根目录即可,例如:

C:\Users\you\myproject\radiant-mass
text

Studio 会自动识别 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 客户端。

每次提交前建议:

  1. 在 Git 页确认改动文件。
  2. 阅读一两次 diff(可以在编辑器或外部 Git 客户端)。
  3. 写清楚提交说明再提交。

终端与全局日志#

「终端与日志」使用 xterm.js 和本地 PTY,在博客根目录启动:

  • Windows 默认 PowerShell。
  • 其他平台使用 $SHELL,回退到 sh。
  • 支持交互输入、Ctrl+C、复制、粘贴、清屏、自适应窗口大小和重新连接。

日志是全局的,保存在应用配置目录的 logs/terminal.log,不随工作区切换清空。每次打开终端都会追加一个会话块,包含时间、工作区和 Shell 名称。

常用命令:

bun run build
npm run build
git status
git log --oneline -20
powershell

终端以当前用户权限运行,没有内置沙箱。只执行你信任的命令。

配置与文件边界#

Studio 主要写入以下位置:

路径用途
site.config.ts站点基础信息、菜单、页脚社交链接
src/pure-studio.config.tsStudio 生成的主题配置覆盖
src/site-content.ts页脚、版权、二维码等文本内容
.pure-studio/site.jsonStudio 自己的站点状态快照
.pure-studio/disabled-pages/被禁用的主题页面目录
应用配置目录的 logs/全局终端日志与临时数据

建议把 .pure-studio/ 加入博客仓库的 .gitignore,除非你希望和团队共享这些本地状态。

构建与测试#

在 Studio 工程内:

npm run check      # 类型检查 + Rollup 构建 + SSR 冒烟测试
npm run typecheck  # 仅类型检查
npm run build      # 仅构建 dist/
npm run smoke      # 离线渲染主要界面
powershell

Rust 测试:

cd src-tauri
cargo test
powershell

npm run check 不需要启动 Tauri 或 WebView2,适合在 CI 或受限环境中先验证前端与视图。

打包桌面应用#

npm run tauri:build
powershell

如果没有 NSIS 工具链,可以只生成可执行文件:

npm run build
cargo build --release --offline --features custom-protocol --manifest-path src-tauri/Cargo.toml
powershell

--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 test
powershell

许可证#

本项目使用 Mozilla Public License 2.0(MPL-2.0) ↗。

你可以自由使用、修改和分发;分发修改后的源文件时,需要继续以 MPL-2.0 提供相应源文件并保留许可证与版权声明。