Alpine.js安装 #

安装方式概览 #

Alpine.js 提供多种安装方式，适应不同的开发场景：

方式	适用场景	难度
CDN 引入	快速原型、简单项目	简单
NPM/Yarn	正式项目、模块化开发	中等
下载本地文件	内网环境、离线开发	简单

方式一：CDN 引入（推荐新手） #

基本用法 #

在 HTML 文件的 <head> 或 <body> 底部添加：

html

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

完整示例 #

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Alpine.js 示例</title>
    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
</head>
<body>
    <div x-data="{ message: 'Hello Alpine!' }">
        <p x-text="message"></p>
    </div>
</body>
</html>

CDN 选项 #

CDN	地址
jsDelivr	`https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js`
unpkg	`https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js`
cdnjs	`https://cdnjs.cloudflare.com/ajax/libs/alpinejs/3.x.x/cdn.min.js`

指定版本 #

html

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

使用 defer #

defer 属性确保 DOM 加载完成后再执行 Alpine.js：

html

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

方式二：NPM/Yarn 安装 #

安装命令 #

bash

npm install alpinejs

或使用 Yarn：

bash

yarn add alpinejs

或使用 pnpm：

bash

pnpm add alpinejs

基本使用 #

在你的 JavaScript 入口文件中：

javascript

import Alpine from 'alpinejs'

window.Alpine = Alpine

Alpine.start()

配合构建工具 #

Vite 配置 #

javascript

import { defineConfig } from 'vite'
import Alpine from 'alpinejs'

export default defineConfig({
    // Vite 配置
})

javascript

import Alpine from 'alpinejs'

window.Alpine = Alpine
Alpine.start()

Webpack 配置 #

javascript

import Alpine from 'alpinejs'

window.Alpine = Alpine
Alpine.start()

模块化组织代码 #

javascript

import Alpine from 'alpinejs'
import { dropdown, modal, tabs } from './components'

Alpine.data('dropdown', dropdown)
Alpine.data('modal', modal)
Alpine.data('tabs', tabs)

Alpine.start()

方式三：下载本地文件 #

下载地址 #

从以下地址下载 Alpine.js 文件：

压缩版：https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js
未压缩版：https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.js

本地引用 #

html

<script defer src="/js/alpinejs.min.js"></script>

安装官方插件 #

CDN 方式安装插件 #

html

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

插件必须在 Alpine.js 核心库之前加载。

NPM 方式安装插件 #

bash

npm install @alpinejs/persist @alpinejs/intersect

javascript

import Alpine from 'alpinejs'
import persist from '@alpinejs/persist'
import intersect from '@alpinejs/intersect'

Alpine.plugin(persist)
Alpine.plugin(intersect)

Alpine.start()

开发环境配置 #

VS Code 扩展推荐 #

安装以下扩展获得更好的开发体验：

Alpine.js IntelliSense - 代码提示
Alpine.js Syntax Highlighting - 语法高亮

配置 VS Code 设置 #

在 .vscode/settings.json 中添加：

json

{
    "tailwindCSS.includeLanguages": {
        "alpine": "html"
    },
    "editor.quickSuggestions": {
        "strings": true
    }
}

ESLint 配置 #

安装 Alpine.js ESLint 插件：

bash

npm install -D eslint-plugin-alpine

.eslintrc.js 配置：

javascript

module.exports = {
    plugins: ['alpine'],
    rules: {
        'alpine/no-invalid-attr': 'error'
    }
}

浏览器开发者工具 #

Alpine.js DevTools #

安装浏览器扩展以调试 Alpine.js 应用：

Chrome: Alpine.js DevTools
Firefox: Alpine.js DevTools

功能包括：

查看组件数据状态
实时修改数据
追踪数据变化

验证安装 #

简单测试 #

创建一个测试页面验证安装是否成功：

html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Alpine.js 安装测试</title>
    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
</head>
<body>
    <div x-data="{ show: false }">
        <button x-on:click="show = !show">
            点击测试 Alpine.js
        </button>
        <p x-show="show" x-text="'Alpine.js 安装成功！'"></p>
    </div>
</body>
</html>

控制台检查 #

打开浏览器控制台，输入：

javascript

console.log(Alpine.version)

如果输出版本号，说明安装成功。

常见问题 #

1. Alpine is not defined #

原因：脚本加载顺序问题

解决：确保使用 defer 属性或把脚本放在 <body> 底部

html

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

2. x-data 相关错误 #

原因：DOM 未加载完成

解决：使用 defer 或 DOMContentLoaded 事件

html

<script defer src="..."></script>

3. 插件不生效 #

原因：插件加载顺序错误

解决：确保插件在 Alpine.js 核心库之前加载

html

<script defer src="插件地址"></script>
<script defer src="Alpine.js核心库地址"></script>

4. 版本冲突 #

原因：同时加载多个版本

解决：只加载一个版本的 Alpine.js

小结 #

本章介绍了 Alpine.js 的三种安装方式：

CDN 引入：最简单，适合快速原型开发
NPM 安装：适合正式项目，支持模块化
本地文件：适合离线或内网环境

选择建议：

学习阶段：使用 CDN 方式
正式项目：使用 NPM 方式
生产环境：考虑使用 CDN + 本地备份

下一章，我们将创建第一个 Alpine.js 应用程序。