如何用Astro生成可本地打开的带相对路径静态HTML

1. 修改astro.config.mjs配置 #

调整配置参数，强制生成相对路径的资源链接与页面链接：

import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
  site: '', // 禁用绝对URL生成，切换为相对路径模式
  base: './', // 锚定所有链接基于当前文件目录
  trailingSlash: 'always', // 确保页面链接指向目录下的index.html
  build: {
    format: 'directory', // 保留目录结构，每个页面对应目录内的index.html
  },
});

2. 调整页面链接写法 #

如果组件中原本使用绝对路径链接（比如<a href="/docs">），需改为以下两种方式之一：

方式一：手动写相对路径 #

直接指定指向index.html的相对路径：

<a href="docs/index.html" class="astro-BIH2FJRL">Docs</a>

方式二：用Astro工具函数生成动态相对链接 #

针对动态生成的链接，使用astro:utils提供的getRelativeUrl自动适配当前页面路径：

---
import { getRelativeUrl } from 'astro:utils';
---

<a href={getRelativeUrl('/docs/index.html')} class="astro-BIH2FJRL">Docs</a>

3. 验证生成结果 #

执行npm run build后，检查生成的HTML文件：

• 样式链接应变为 <link rel="stylesheet" href="_astro/hoisted.83c691aa.css" />（或带./前缀）
• 页面跳转链接应变为 <a href="docs/index.html" class="astro-BIH2FJRL">Docs</a>

此时直接从本地文件系统打开生成的index.html，所有资源加载和页面跳转均可正常工作，无需依赖服务器或CDN。

内容的提问来源于stack exchange，提问作者Wiktor Kęska