Astro项目导入依赖window/document的导航JS遇报错求助

问题根源 #

Astro组件的frontmatter代码是在服务器端执行的，你直接在这里导入依赖window/document的脚本时，脚本会在服务器环境运行，自然触发"Browser APIs are not available on the server"报错。

正确解决方案 #

1. 移到HTML区域用<script>标签引入

把脚本导入逻辑从frontmatter移到Header.astro的HTML区域，Astro会自动将这类脚本标记为客户端执行，不会在服务器端运行：

---
// frontmatter内删除导入脚本的代码
---
<header>
  <!-- 你的导航HTML结构 -->
  <script src="../js/menu.js"></script>
</header>

2. 针对ES模块化脚本的处理

如果你的menu.js是ES模块（使用了import/export），给脚本标签加上type="module"：

<script type="module" src="../js/menu.js"></script>

3. 修复is:inline无效的问题

你之前用is:inline后报错消失但脚本不工作，大概率是脚本执行时机早于DOM加载完成，导致找不到目标元素。两种解决办法：

• 修改脚本，延迟到DOM就绪后执行：
  把menu.js里的逻辑包裹在DOMContentLoaded事件监听中：

  document.addEventListener('DOMContentLoaded', () => {
    // 原导航逻辑，比如获取菜单按钮、绑定点击事件
    const menuToggle = document.querySelector('.menu-toggle');
    const navMenu = document.querySelector('.nav-menu');
    
    if (menuToggle && navMenu) {
      menuToggle.addEventListener('click', () => {
        navMenu.classList.toggle('open');
      });
    }
  });
  

• 给脚本标签加defer属性：
  defer会让脚本在DOM加载完成后再执行，无需修改脚本内容：

  <script is:inline src="../js/menu.js" defer></script>
  

4. 使用Astro客户端指令（推荐）

如果想在组件内直接写脚本逻辑或导入模块，用Astro的客户端指令强制在浏览器端执行，比如client:load：

<script client:load>
  import '../js/menu.js';
</script>

client:load会在页面加载时立即在客户端执行脚本，确保window/document等API可用。

内容的提问来源于stack exchange，提问作者2536817