Astro报错TypeError: Cannot read properties of undefined (reading 'document')求助

问题原因 #

你在Astro布局文件的前置脚本（---代码块）中直接import jQuery，而这个脚本是在Node.js服务端环境运行的，jQuery依赖浏览器的document对象，服务端没有这个对象，所以会抛出Cannot read properties of undefined (reading 'document')错误。

解决方案 #

方式1：直接在HTML中用<script>标签引入 #

把jQuery和自定义脚本放在HTML的<body>末尾（确保页面DOM加载完成后执行），代码示例：

---
---

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <!-- 页面头部内容 -->
</head>
<body>
  <!-- 页面主体内容 -->
  
  <!-- 引入脚本 -->
  <script src="../scripts/jquery.js"></script>
  <script src="../scripts/main.js"></script>
</body>
</html>

方式2：使用Astro的is:client指令 #

如果想利用Astro的资源打包能力，可以给脚本标签加上is:client属性，让脚本只在浏览器端加载执行，避免服务端运行报错：

---
---

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <!-- 页面头部内容 -->
</head>
<body>
  <!-- 页面主体内容 -->
  
  <script is:client src="../scripts/jquery.js"></script>
  <script is:client src="../scripts/main.js"></script>
</body>
</html>

注意事项 #

• 确保jQuery脚本在自定义main.js之前引入，保证main.js执行时jQuery已经加载完成。
• 不要在Astro的前置脚本块中import浏览器端依赖（比如jQuery、DOM操作类库），这类脚本只能在浏览器环境运行。

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