AlpineJS在Django模板部署时出现'app未定义'错误求助

问题描述 #

部署Django项目后，AlpineJS抛出以下错误：

Alpine Expression Error: app is not defined
Expression: "app"

本地运行无此问题，相关配置如下：

• 项目base.html的<head>中加载AlpineJS：

<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

• </body>闭合标签上方加载自定义JS文件：

<script src="{% static 'js/main.js' %}"></script>

• main.js内容：

window.addEventListener('load', function () {
  Alpine.data('app', () => ({
    modalOpen: false,
    mobileNavOpen: false,
    toggleModal() {
      this.modalOpen = !this.modalOpen
      document.body.classList.toggle('overflow-hidden')
    },
    toggleMobileNav() {
      this.mobileNavOpen = !this.mobileNavOpen
    },
  }))
})

• <body>标签绑定x-data：

<body class="front bg-slate-50" x-data="app">

问题原因 #

核心是代码执行时机不匹配：

1. AlpineJS脚本带有defer属性，会在DOM解析完成后执行，但不会等待其他资源加载；
2. window.load事件需要等页面所有资源（图片、字体等）加载完成才触发，部署后网络环境下，AlpineJS会先完成DOM解析并尝试读取x-data="app"，但此时Alpine.data('app')还未注册，因此报错。本地环境资源加载快，触发顺序刚好符合预期，所以未暴露问题。

解决方案 #

方案一：使用Alpine官方初始化事件（推荐） #

将main.js中的window.load事件替换为Alpine提供的alpine:init事件，该事件会在Alpine准备好注册数据组件时触发，确保注册时机正确：

document.addEventListener('alpine:init', () => {
  Alpine.data('app', () => ({
    modalOpen: false,
    mobileNavOpen: false,
    toggleModal() {
      this.modalOpen = !this.modalOpen
      document.body.classList.toggle('overflow-hidden')
    },
    toggleMobileNav() {
      this.mobileNavOpen = !this.mobileNavOpen
    },
  }))
})

方案二：调整脚本加载顺序 #

1. 去掉AlpineJS脚本的defer属性：

<script src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

2. 将main.js脚本移到AlpineJS脚本之后加载（比如放在<head>中Alpine脚本的下方），确保Alpine先加载完成，再执行数据注册逻辑。

这种方式可能会阻塞DOM解析，影响页面加载速度，因此不如方案一优雅。

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