前言#

在原生 Astro 或 Fuwari 主题中，文章正文里的外部链接默认在当前页面打开。对教程类文章来说这体验并不友好——读者点开一个参考资料，正在读的文章就被顶掉了，回来还得重新找位置。

想要的效果很简单：

• 这是站内链接（当前窗口打开）
• 这是外部链接（新标签页打开）

两者的 HTML 只差一个属性：

1
<a href="https://www.bing.com">当前窗口打开</a>
2
<a href="https://www.bing.com" target="_blank">新标签页打开</a>

NOTE

本文于 2026-09-12 基于本站的实际实现重写：除介绍社区常用的 rehype-external-links 方案外，重点补充本站采用的零依赖自写插件方案，以及排查过程中踩到的几个坑。

原理：三十秒讲清#

Markdown 里的 [文字](链接) 经过 remark 解析后，会变成一棵 hast 树（HTML 的 AST）里的 element 节点，标签名是 a。Astro 的 Markdown 管线在生成 HTML 字符串之前，会依次把 rehypePlugins 里的插件跑一遍，每个插件都能拿到并修改这棵树。

所以这件事的本质就是：插一个 rehype 插件进去，遍历这棵树，给外链的 a 节点加上 target="_blank"。

1
Markdown → remark 解析 → mdast → remark-rehype → hast →【rehype 插件们】→ HTML

关键位置在 astro.config.mjs 的 markdown.rehypePlugins 数组。

两条路线怎么选#

本站选了路线 B：需求只有”外链加 _blank”这一条，而本机 pnpm install 装本地包时曾经卡死过十几分钟，为一个 20 行的功能引一个新依赖不划算。

路线 A：装 rehype-external-links#

1
pnpm add rehype-external-links

然后在 astro.config.mjs 里引入并挂到 rehypePlugins：

1
import rehypeExternalLinks from "rehype-external-links";
2

3
// markdown.rehypePlugins 数组中新增一项：
4
rehypePlugins: [
5
    rehypeKatex,
6
    rehypeSlug,
7
    [rehypeExternalLinks, { target: "_blank", rel: ["noopener", "noreferrer"] }],
8
    // ...其他插件
9
],

这一行的效果等价于路线 B，区别只是逻辑由社区包实现。

路线 B：零依赖自写插件（本站采用）#

1
/**
2
 * 给文章正文中的外部链接（http/https 绝对地址）自动添加 target="_blank"。
3
 * 站内相对链接与页内锚点不受影响，保持当前窗口打开（Swup 无刷新导航）。
4
 * 零依赖实现：手动遍历 hast 树，避免引入 rehype-external-links。
5
 */
6
export function rehypeExternalTarget() {
7
    return (tree) => {
8
        const walk = (node) => {
9
            if (!node || typeof node !== "object") return;
10
            if (node.type === "element" && node.tagName === "a") {
11
                const href = node.properties && node.properties.href;
12
                if (typeof href === "string" && /^https?:\/\//i.test(href)) {
13
                    node.properties.target = "_blank";
14
                    // rel 覆盖写（防止新标签页通过 window.opener 反向操作原页面）
15
                    node.properties.rel = "noopener noreferrer";
16
                }
17
                return; // 命中 a 就收，不深入其内部子节点
18
            }
19
            if (Array.isArray(node.children)) node.children.forEach(walk);
20
        };
21
        walk(tree);
22
    };
23
}

1
// 1. 顶部 import（与其他插件 import 放一起）
2
import { rehypeExternalTarget } from "./src/plugins/rehype-external-target.mjs";
3

4
// 2. markdown.rehypePlugins 数组中加一项（位置随意，建议放在 rehypeSlug 之后）
5
rehypePlugins: [
6
    rehypeKatex,
7
    rehypeSlug,
8
    rehypeExternalTarget,
9
    // ...其他插件
10
],

怎么验证真的生效#

1
node --input-type=module -e '
2
import { rehypeExternalTarget } from "./src/plugins/rehype-external-target.mjs";
3
const tree = { type: "root", children: [
4
  { type: "element", tagName: "p", children: [
5
    { type: "element", tagName: "a", properties: { href: "https://example.com/x" }, children: [] },
6
    { type: "element", tagName: "a", properties: { href: "/posts/foo/" }, children: [] },
7
    { type: "element", tagName: "a", properties: { href: "#section-1" }, children: [] },
8
    { type: "element", tagName: "a", properties: { href: "HTTPS://EXAMPLE.ORG" }, children: [] },
9
  ]},
10
]};
11
rehypeExternalTarget()(tree);
12
const out = [];
13
const walk = (n) => { if (!n || typeof n !== "object") return;
14
  if (n.type === "element" && n.tagName === "a") out.push(n.properties.href + " -> target:" + n.properties.target);
15
  if (Array.isArray(n.children)) n.children.forEach(walk); };
16
walk(tree);
17
console.log(out.join("\n"));
18
'

1
node --input-type=module -e '
2
const res = await fetch("http://127.0.0.1:4321/posts/<文章 slug>/");
3
const html = await res.text();
4
const i = html.indexOf("你要检查的外链域名");
5
console.log(html.slice(html.lastIndexOf("<a", i), i + 120));
6
'

三个容易踩的坑#

IMPORTANT

① 改完 astro.config.mjs 必须手动重启 dev server。 页面和组件的改动会热更新，但 astro.config.mjs 是服务级配置——Astro 只在启动时读一次。本站排查时就被这个坑过：配置确认已落盘、插件单元测试也通过，但页面上就是没有 target，重启 dev server 后立即生效。

② 别用 node -e 直接 import unified / remark-parse 来验证。 在 pnpm 的严格模式（isolated node_modules）下，这些是传递依赖，不在顶层 node_modules，直接 import 会报 ERR_MODULE_NOT_FOUND。要验证插件行为，用上面「方法一」造树的方式，绕开整个 unified 链路。

③ 手写 <a> 标签不受这个插件影响。 rehype 插件只处理 Markdown 渲染产物。像友链页里手写的卡片链接、导航栏链接这类直接写在 .astro 里的 <a>，要新窗口打开就得自己加 target="_blank"——本站 friends.astro 的友链外链按钮就是手写的。

一点补充：为什么不干脆全部开新窗#

内部链接保持当前窗口，是为了不破坏 Swup 的无刷新切换；外链开新窗，是为了保住读者的阅读位置。判断标准不是”是不是本站的链接”，而是”跳转后会不会中断阅读”。

顺着这个思路，本站的做法是：正文外链（插件自动）→ 新窗；站内导航 / 锚点（放过）→ 当前窗；友链卡片（手写）→ 新窗。

相关阅读#

• Markdown 求职实录：一场兼作本站 Markdown 样式陈列的面试——本站 Markdown 与 Expressive Code 语法的陈列与对照
• Expressive Code 官方文档