在 Astro 中实现 Obsidian 风格的 Wiki Link 内部链接

slug 才是 URL 的来源#

直觉上「文件路径决定 URL」：src/content/posts/foo.md → /posts/foo/，guide/index.md → /posts/guide/。转换代码也就这么写：

1
function createPostUrl(contentPath) {
2
  const segments = contentPath.split("/");
3

4
  if (segments.at(-1)?.toLowerCase() === "index") {
5
    segments.pop();
6
  }
7

8
  const encodedPath = segments.map(encodeURIComponent).join("/");
9
  return `/posts/${encodedPath ? `${encodedPath}/` : ""}`;
10
}

但这只是默认规则。文章页是 [...slug].astro 动态路由，参数取自 removeFileExtension(entry.id)——真正决定 URL 的是 entry.id。而 glob loader 生成 id 时有个容易看漏的行为：它先读原始 frontmatter，里面有 slug 就直接拿来当 id，没有才回退到文件路径。

这一点从 schema 里完全看不出来。Firefly 的 posts schema 根本没声明 slug 字段，z.object 默认剥掉未声明的键，所以 entry.data.slug 永远是 undefined。看代码很容易得出「slug 是个被忽略的遗留字段」的结论——我当时就是这么判断的，还差点据此把插件里的 slug 匹配删掉。

真相是它在 schema 校验之前就已经改掉了路由。验证只要一分钟：给 zz-test.md 写上 slug: zz-alias，/posts/zz-alias/ 返回 200，/posts/zz-test/ 返回 404。

所以插件里绝不能拿「链接里写了什么」去拼 URL，得先解析到具体文件，再由文件反推 id：

1
function toPostId(meta) {
2
  const declaredSlug =
3
    typeof meta.data.slug === "string" ? meta.data.slug.trim() : "";
4

5
  // frontmatter slug 优先，与 glob loader 的 generateId 保持一致
6
  return declaredSlug || toContentPath(meta.filePath);
7
}

顺带说，slug 优先也让文章能自由改名、挪目录，而不影响已有的 wiki link 引用。

一次遍历，mtime 缓存#

第一步和第三步都需要「全站文章的 frontmatter」，所以干脆一次走完整棵目录树，读到的每份 frontmatter 按文件修改时间缓存：

1
function collectPostMetas() {
2
  const metas = [];
3
  const stack = [POSTS_DIR];
4

5
  while (stack.length > 0) {
6
    const dir = stack.pop();
7
    let entries;
8
    try {
9
      entries = readdirSync(dir, { withFileTypes: true });
10
    } catch {
11
      // 目录读不到就跳过；注意这里只包住 readdirSync，
12
      // 避免把下面的逻辑错误一起吞掉
13
      continue;
14
    }
15

16
    for (const entry of entries) {
17
      const fullPath = path.join(dir, entry.name);
18
      if (entry.isDirectory()) {
19
        stack.push(fullPath);
20
      } else if (MARKDOWN_EXTENSION.test(entry.name)) {
21
        const meta = readMetaFile(fullPath); // 内含 mtime 缓存
22
        if (meta) metas.push(meta);
23
      }
24
    }
25
  }
26

27
  return metas;
28
}

用显式栈而不是递归，纯粹是懒得想目录深度。

裸文件名只在唯一时接受#

第三步是为 Obsidian 加的，理由在下一节。它的两条约束值得单独说：

1
function findMetaByBaseName(metas, target) {
2
  if (target.includes("/")) return null;
3

4
  const matches = metas.filter(
5
    (meta) =>
6
      path.basename(meta.filePath).replace(MARKDOWN_EXTENSION, "") === target,
7
  );
8

9
  if (matches.length === 1) return matches[0];
10
  if (matches.length > 1) {
11
    console.warn(`[remark-wiki-link] "[[${target}]]" 匹配到多个同名文件，已跳过：...`);
12
  }
13
  return null;
14
}

重名时不猜。 放弃匹配并打一条构建期警告，而不是取第一个。这和 Obsidian 自己的行为一致——它在重名时也会自动改用更长的路径。要是静默挑一个，改动一个不相关目录里的文件名，就可能让另一篇文章的链接悄悄指向别处，而且构建照样成功。

必须排在最后。 裸文件名要让位给精确路径匹配，否则 [[index]] 会绕过根目录下真实存在的 index.md，跑去撞某个子目录里的同名文件。

「尽可能简短的形式」#

设置 → 文件与链接 → 链接 → 内部链接类型 的默认值是尽可能简短的形式：只要文件名在整个仓库里唯一，插入的链接就只有文件名，不带任何目录。于是 dev-notes/ 下的文章会被写成 [[astro-wiki-link-implementation]]。

按前两级规则，这个链接既匹配不到 slug（slug 是完整路径），也匹配不到根目录下的同名文件，最后拼出 /posts/astro-wiki-link-implementation/——404。

本来可以在文档里写一句「请把这个设置改成基于仓库根目录的绝对路径」了事，但这是 Obsidian 的默认值，还藏在三级菜单里。指望每个用户先踩坑再去翻设置，不如让插件认下这种写法。

这一步同时把上面「URL 从解析结果反推」从设计偏好变成了硬性要求：链接文字是 astro-wiki-link-implementation，解析到的文件却在 dev-notes/ 下，URL 只能由 toPostId(meta) 算。继续拿链接文字拼 URL 的话，裸文件名支持就是一个稳定生成 404 的功能。

别名不一定是别名#

改成基于仓库根目录的绝对路径之后，Obsidian 插入的是这个：

1
[[guide/firefly-layout-system|firefly-layout-system]]

它自动补了一个等于文件名的别名，好让笔记里显示的不是一长串路径。对 Obsidian 来说这是纯粹的显示优化，可插件这边一视同仁地把别名当作者指定的标题，卡片标题就成了 firefly-layout-system，而不是文章真正的 title。

有两个方向可选：换一个 Obsidian 不会生成的自定义标题语法，或者识别出这种「别名只是把链接目标又抄了一遍」的情况并忽略它。前者的代价是新语法在 Obsidian 里不被识别，会按原文显示、也点不动——为了修一个显示问题，牺牲另一边的显示，不划算。

于是走后者：

1
function resolveAlias(parsed, meta) {
2
  if (!parsed.alias) return "";
3

4
  const noise = new Set([
5
    parsed.destination,
6
    parsed.contentPath,
7
    path.basename(parsed.contentPath),
8
  ]);
9
  if (meta) {
10
    noise.add(toContentPath(meta.filePath));
11
    noise.add(path.basename(meta.filePath).replace(MARKDOWN_EXTENSION, ""));
12
  }
13

14
  return noise.has(parsed.alias) ? "" : parsed.alias;
15
}

除了链接里写的路径，也拿解析到的真实文件名比一遍。因为 Obsidian 补的别名对应的是它自己算出的最短形式，在 slug 写法下可能和链接文字里的任何一段都不相等。

代价是没法故意让显示文字等于文件名了。这个功能的用户是零，需要的话写 Markdown 原生链接更直白。

相对路径不支持#

下拉框第三个选项基于当前笔记的相对路径只在同目录内可用：同目录文章生成的是裸文件名，第三级规则能接住；跨目录会生成 ../ 前缀，被 normalizeContentPath 的 .. 检查挡掉，链接按原文显示。

这个不打算支持。.. 检查是安全边界，为了一个能靠改设置绕开的便利去开口子不值得。

怎么判断「独立成段」#

1
function tryCreateCardFromParagraph(node, context) {
2
  if (node.type !== "paragraph" || node.children?.length !== 1) return null;
3

4
  const child = node.children[0];
5
  if (child.type !== "text") return null;
6

7
  const match = child.value.trim().match(STANDALONE_WIKI_LINK);
8
  if (!match) return null;
9

10
  const parsed = parseWikiLinkValue(match[1]);
11
  if (!parsed || parsed.heading || !parsed.contentPath) return null;
12

13
  return createWikiLinkCard(parsed, context);
14
}

唯一被排除的是 [[slug#标题]]。锚点的语义是「跳到那一段」而不是「引用整篇文章」，做成卡片会误导：卡片展示整篇文章的元数据，点进去却落在中间某处。

[[slug|别名]] 起初也在排除名单里，后来放开了。别名和「是否引用整篇文章」是两件正交的事——写 [[firefly|主题介绍]] 的人只是嫌原标题太长，并不想降级成普通链接。放开后别名接管卡片标题，其余字段照旧从目标文章读：

1
const title =
2
  resolveAlias(parsed, meta) ||
3
  (typeof meta.data.title === "string" && meta.data.title
4
    ? meta.data.title
5
    : resolvedPath);

代价是失去一个隐式逃生舱——原先「想让独立成段的链接保持普通样式，就随便加个别名」的技巧没了。不过那本来是靠副作用实现的，不算正经 API。

组装 DOM#

remark 阶段只能操作 mdast，输出不了 HTML。hName/hProperties 是 unified 生态的标准做法，让 mdast 节点在转 hast 时映射到指定标签和属性：

1
function createElement(tagName, properties, children) {
2
  return {
3
    type: "paragraph",
4
    data: { hName: tagName, hProperties: properties },
5
    children,
6
  };
7
}
8

9
createElement("a", { class: "card-wiki-link no-styling", href: url }, [
10
  createElement("div", { class: "wlc-info" }, [
11
    createElement("div", { class: "wlc-title" }, [createText(title)]),
12
    createElement("div", { class: "wlc-description" }, [createText(description)]),
13
    createElement("div", { class: "wlc-meta" }, metaItems),
14
  ]),
15
  createElement("div", { class: "wlc-cover" }, [cover]),
16
]);

type 写成 paragraph 只是为了让 mdast-util-to-hast 愿意处理它，实际标签由 hName 决定。描述、日期、分类、标签、封面都是缺了就不生成对应节点，而不是留个空容器——省掉一堆「空元素也占 margin」的样式补丁。

加密文章（frontmatter 里有 password）的描述会被跳过，只留标题和时间，避免把内容摘要泄在卡片上。

三种来源#

1
function createCoverNode(meta, resolvedPath, context) {
2
  const image = meta.data.image;
3

4
  // 1. 随机封面 API
5
  if (image === "api") {
6
    const seed = resolvedPath.replace(/\/index$/i, "");
7
    return createElement("div", {
8
      class: "cover-image-container",
9
      dataApiUrls: JSON.stringify(getApiUrlList(image, seed)),
10
    }, [createRemoteCoverImg(processCoverImageSync(image, seed))]);
11
  }
12

13
  // 2. 远程 URL 或 public 目录
14
  if (/^(?:https?:)?\/\//i.test(image) || image.startsWith("/")) {
15
    return createRemoteCoverImg(image);
16
  }
17

18
  // 3. 本地相对路径 → 交给 Astro 图片管线
19
  return {
20
    type: "image",
21
    url: coverUrl,
22
    alt: "",
23
    data: { hProperties: { width: 480 } },
24
  };
25
}

随机封面那条的 seed 要和 PostCard、文章页算出来的完全一致，否则同一篇文章在列表和卡片里会抽到不同的图。seed 用的是 entry.id，而 entry.id 已经去掉了末尾的 /index，所以这里得手动补上同样的处理——又一处「跟着 Astro 的隐式规则走」。

哈希对不上的变体#

本地图片走 rehypeImages，最终调 getImage() 生成优化变体。Astro 用 hashTransform 算输出文件名，输入包括 src、width、height、format、quality。

问题是：文章列表的 <Image> 组件传入的 src 是 ESM import 对象（Vite 模块引用），markdown 管线传入的是相对路径字符串。其他参数完全一致，hashTransform 的结果也不同——同一张图生成两份几乎相同的变体。

试过用 import.meta.glob 在插件里拿到 ESM import 对象来对齐哈希，但 remark 是同步上下文，而 import.meta.glob({ eager: true }) 返回的对象在不同构建阶段身份不同，始终对不上。

最后接受多一份变体，但把 width 压到 480px（列表用 640px）。实测 480w 比 640w 小约 46%，三张封面总共多约 66KB，换来的是不用跟 Astro 的内部哈希逻辑硬碰。

被 try/catch 吞掉的 ReferenceError#

三级解析刚写完时，slug 匹配一次都没生效过，但页面完全正常——因为文件路径匹配兜住了所有链接，肉眼看不出区别。

原因是 readdirSync 外面套着一层 try/catch（目录不存在时要静默跳过），而当时只从 node:fs 导入了 readFileSync 和 statSync，代码里写的是 fs.readdirSync——fs 是个未定义标识符。抛出的不是预期的 ENOENT，而是 ReferenceError，被同一个 catch 咽下，函数返回 null，安静地退化成纯路径匹配。

1
try {
2
  entries = readdirSync(dir, { withFileTypes: true });
3
} catch {
4
  return null; // 本意是跳过读不到的目录，实际把 ReferenceError 也一起咽了
5
}

catch {} 的捕获范围比想象的宽：它不只接住你预期的那类 IO 错误，也接住拼写错误、未定义变量、TypeError 这些本该在开发阶段就炸出来的问题。写宽泛的 catch 至少要判一下错误类型，或者留条日志。静默失败叠加一条刚好能兜住的回退路径，是最难发现的一类 bug。

内容缓存不认插件改动#

改完插件、重启 dev server，卡片的 href 还是旧的。

Astro 把内容集合的渲染结果缓存在 .astro/data-store.json，失效判断看的是内容文件本身有没有变。插件代码改了但文章没改，缓存照样命中，页面渲染的是上一版插件的输出。

1
rm -f .astro/data-store.json

删掉再重启就好了。调试 remark 插件时，「改了没效果」优先怀疑这个，而不是怀疑自己的逻辑——我在一个已经修好的 bug 上多花了十几分钟，就因为看到的还是修复前的 href。