目录11
写作工作流
写作工作流
这篇说明「在 Obsidian 写笔记 → 发布到博客」的完整流程。
数据流
你的笔记（位置任意） Astro 站点
───────────────── ──────────────────
任意路径/我的笔记.md ──npm run pub──▶ src/content/blog/我的笔记.md
（原生语法，永不改） 转换 （标准 markdown，构建输入）
任意路径/图片目录/ │
│ ▼
└────图片复制──▶ public/attachments/我的笔记/
│
▼
npm run build
│
▼
dist/ 静态站点核心原则：源文件永不修改。 发布脚本只读它、转换后写到别处。 这样 Obsidian 里始终是原生语法（图片正常显示、双链可跳转）， 博客拿到的是干净的标准 markdown。
日常流程
最常用：指定一篇笔记 + 它的附件目录
node scripts/publish.mjs "E:/笔记/机器学习.md" --img "E:/笔记/附件"附件目录可以给多个（同一张图散在几个地方也没问题）：
node scripts/publish.mjs "E:/笔记/ML.md" \
--img "E:/笔记/附件" \
--img "E:/图库/截图" \
--img "D:/其他/配图"-i 是 --img 的简写：
node scripts/publish.mjs "E:/笔记/ML.md" -i "E:/笔记/附件" -i "E:/图库"也可以给目录（发布目录下全部 .md）
node scripts/publish.mjs "E:/笔记/博客" --img "E:/笔记/博客/附件"完整流程
# 1. 在 Obsidian 里写完，确认图片都放好了
# 2. 看一眼会做什么（不写文件）
node scripts/publish.mjs "E:/笔记/ML.md" -i "E:/笔记/附件" --dry-run
# 3. 发布
node scripts/publish.mjs "E:/笔记/ML.md" -i "E:/笔记/附件"
# 4. 校验图片引用（会列出命中失败的）
npm run check
# 5. 预览
npm run dev命令一览
| 选项 | 作用 |
|---|---|
--img <目录> / -i <目录> |
图片查找目录，可给多次 |
--dry-run |
只看会做什么，不写文件 |
--force |
覆盖 src/content/blog/ 里已存在的同名文件 |
--keep-images |
不复制图片（图片已在 public/ 里） |
--flat |
图片直接放 public/attachments/ 下，不按文章名分目录 |
不带任何路径参数时，退化为旧行为：发布 obsidian/博客/ 下全部，
附件按文件名匹配。
图片怎么被找到
按你给的目录顺序找，每个目录也会看一层子目录：
- 每个
--img指定的目录（含其一层子目录） - 笔记文件自己所在的目录（含其一层子目录）
允许省略扩展名 —— 写 ![[截图]] 会依次试
.png / .jpg / .jpeg / .gif / .webp / .svg / .bmp / .avif。
图片在站点上的位置
<任意源路径>/截图.png
→ public/attachments/<文章名>/截图.png
→ 引用写作 /attachments/<文章名>/截图.png这条规则与源目录无关，只取决于文章名。所以：
- 换源目录、换笔记放哪都不影响 —— 不会出现「引用与文件对不上、图片全 404」
- 不同笔记的同名图片互不干扰（各自在自己的子目录下）
- 加
--flat则统一放public/attachments/，不分子目录
路径里的中文与空格用 encodeURI 编码（空格 → %20、中文 → 百分号编码）。
脚本做了什么
| Obsidian 写法 | 发布后 | 说明 |
|---|---|---|
![[图.png]] |
 |
并复制图片到 public/ |
![[图.png|600]] |
同上，尺寸丢弃 | Obsidian 的显示宽度，Astro 按容器自适应 |
![[图]] |
同上 | 省略扩展名，自动试所有图片扩展名 |
 |
 |
相对路径 → 站点绝对路径 |
 |
同上，尺寸丢弃 | |
 |
原样 | 外链不动 |
 |
原样 | 已是绝对路径 |
[[某笔记]] |
保留并警告 | 本站未启用 wikilinks，会显示成 [[某笔记]] |
> [!note] 标题 |
蓝框 | callout 照常转换 |
frontmatter 缺 date |
自动补（用文件 mtime） | 缺了会导致整篇构建失败 |
常见问题
图片 404
跑 npm run check，它会列出所有命中失败的引用。
注意它已排除代码块与行内代码里的示例文字，报出来的都是真问题。
「找不到图片」
图片不在你给的任何一个 --img 目录里。检查三件事：
目录路径拼对了吗、文件名与笔记里写的完全一致吗
（中文文件名容易差一两个字符）、图片是不是在更深层的子目录里
（脚本只看一层）。
「已存在，跳过」
src/content/blog/ 里已有同名文件。加 --force 覆盖 ——
但注意这会丢掉你对已发布文章的直接修改，改旧文建议直接编辑
src/content/blog/ 下的那份。
在 Obsidian 里设置附件位置
设置 → 文件与链接 → 附件默认位置选「当前文件夹下的指定文件夹」，
填 附件。这样所有图片自动进同一目录，发布时一个 --img 就够。
为什么不自动监听
Obsidian 存盘非常频繁（改一个字就触发），监听会导致 dev server 反复重建。 手动触发更可控 —— 发布前你还能在 Obsidian 里预览效果。
与「直接编辑 src/content/blog」的关系
两种方式并存，按场景选：
| Obsidian → 发布 | 直接编辑 src/content/blog/ |
|
|---|---|---|
| 图片 | Obsidian 里能正常显示 | 看不到图（那些是绝对路径） |
| 双链 | 可跳转 | 无效 |
| 语法 | Obsidian 原生 | 已是标准 md |
| 适合 | 新文章、需要配图 | 改旧文、微调措辞 |
改已有文章时两种都行 —— 直接改 src/content/blog/ 下那份即可，
重新发布需要加 --force（会覆盖）。