在 Astro 中集成 Vue.js：静态与动态组件的完整指南#

一、Astro 与 Vue.js 集成概览#

1.1 集成优势#

特性	优势
部分 Hydration	只激活必要的 Vue 组件，减少 JS 体积
框架无关	可在同一页面混合使用 Vue、React、Svelte 等
性能优先	默认生成静态 HTML，按需添加交互性
开发体验	保持 Vue 的开发习惯和工具链
渐进增强	从静态内容逐步增加 Vue 交互性

1.2 两种 Vue 组件模式#

在 Astro 中，Vue 组件有两种使用方式：

静态 Vue 组件：在构建时渲染为静态 HTML，无客户端 JavaScript
动态 Vue 组件：在客户端激活（hydrate），具有完全交互性

二、基础配置与安装#

2.1 安装依赖#

1
# 在现有 Astro 项目中添加 Vue 支持
2
npm install @astrojs/vue vue
3

4
# 或创建包含 Vue 的新 Astro 项目
5
npm create astro@latest -- --template framework-vue
6

7
# 可选：TypeScript 支持
8
npm install -D @types/vue

2.2 配置 Astro#

1
import { defineConfig } from 'astro/config';
2
import vue from '@astrojs/vue';
3

4
export default defineConfig({
5
  // 启用 Vue 集成
6
  integrations: [vue()],
7

8
  // Vue 特定配置
9
  vite: {
10
    // 可自定义 Vue 插件
11
    plugins: [],
12

13
    // 别名配置（可选）
14
    resolve: {
15
      alias: {
16
        '@': '/src',
17
        '@components': '/src/components',
18
      },
19
    },
20
  },
21
});

2.3 项目结构建议#

1
src/
2
├── components/
3
│   ├── vue/          # Vue 组件
4
│   │   ├── static/   # 静态 Vue 组件
5
│   │   ├── dynamic/  # 动态 Vue 组件
6
│   │   └── shared/   # 共享 Vue 组件
7
│   ├── astro/        # Astro 组件
8
│   └── layouts/      # 布局组件
9
├── pages/           # 页面文件
10
├── stores/          # 状态管理（如 Pinia）
11
├── composables/     # Vue 组合式函数
12
└── utils/           # 工具函数

三、静态 Vue 组件#

3.1 什么是静态 Vue 组件？#

静态 Vue 组件在构建时被渲染为纯 HTML，不包含任何客户端 JavaScript。它们适用于：

纯展示性内容
不需要交互的 UI 部分
性能关键路径上的组件

3.2 创建静态 Vue 组件#

1
<template>
2
  <article class="product-card">
3
    <div class="product-image">
4
      <img
5
        :src="product.image"
6
        :alt="product.name"
7
        loading="lazy"
8
      >
9
    </div>
10

11
    <div class="product-content">
12
      <h3 class="product-name">{{ product.name }}</h3>
13

14
      <div class="product-price">
15
        <span class="current-price">¥{{ product.price }}</span>
16
        <s v-if="product.originalPrice" class="original-price">
17
          ¥{{ product.originalPrice }}
18
        </s>
19
      </div>
20

21
      <div class="product-tags">
22
        <span
23
          v-for="tag in product.tags"
24
          :key="tag"
25
          class="tag"
26
        >
27
          {{ tag }}
28
        </span>
29
      </div>
30

31
      <div class="product-meta">
32
        <span class="rating">
33
          ★ {{ product.rating }}/5.0
34
        </span>
35
        <span class="reviews">
36
          {{ product.reviewCount }} 条评价
37
        </span>
38
      </div>
39
    </div>
40
  </article>
41
</template>
42

43
<script setup>
44
// 接收 props，但在静态模式下不会在客户端执行
45
const props = defineProps({
46
  product: {
47
    type: Object,
48
    required: true,
49
    default: () => ({
50
      id: '',
51
      name: '',
52
      image: '',
53
      price: 0,
54
      originalPrice: null,
55
      tags: [],
56
      rating: 0,
57
      reviewCount: 0,
58
    }),
59
  },
60
});
61
</script>
62

63
<style scoped>
64
.product-card {
65
  border: 1px solid #e5e7eb;
66
  border-radius: 12px;
67
  overflow: hidden;
68
  transition: transform 0.2s ease;
69
}
70

71
.product-card:hover {
72
  transform: translateY(-4px);
73
}
74

75
.product-image {
76
  aspect-ratio: 1/1;
77
  overflow: hidden;
78
}
79

80
.product-image img {
81
  width: 100%;
82
  height: 100%;
83
  object-fit: cover;
84
  transition: transform 0.3s ease;
85
}
86

87
.product-card:hover .product-image img {
88
  transform: scale(1.05);
89
}
90

91
.product-content {
92
  padding: 1rem;
93
}
94

95
.product-name {
96
  font-size: 1.125rem;
97
  font-weight: 600;
98
  margin: 0 0 0.5rem 0;
99
  color: #1f2937;
100
}
101

102
.product-price {
103
  display: flex;
104
  align-items: center;
105
  gap: 0.5rem;
106
  margin-bottom: 0.75rem;
107
}
108

109
.current-price {
110
  font-size: 1.25rem;
111
  font-weight: bold;
112
  color: #ef4444;
113
}
114

115
.original-price {
116
  font-size: 0.875rem;
117
  color: #9ca3af;
118
}
119

120
.product-tags {
121
  display: flex;
122
  flex-wrap: wrap;
123
  gap: 0.25rem;
124
  margin-bottom: 0.75rem;
125
}
126

127
.tag {
128
  padding: 0.25rem 0.5rem;
129
  background-color: #f3f4f6;
130
  border-radius: 4px;
131
  font-size: 0.75rem;
132
  color: #4b5563;
133
}
134

135
.product-meta {
136
  display: flex;
137
  justify-content: space-between;
138
  font-size: 0.875rem;
139
  color: #6b7280;
140
}
141
</style>

3.3 在 Astro 中使用静态 Vue 组件#

1
---
2
import StaticProductCard from '../../components/vue/static/ProductCard.vue';
3
import { getProduct } from '../../api/products';
4

5
// 获取静态数据
6
const product = await getProduct(Astro.params.id);
7
---
8

9
<html lang="zh-CN">
10
<head>
11
  <title>{product.name} - 产品详情</title>
12
</head>
13
<body>
14
  <main class="product-page">
15
    <!-- 静态 Vue 组件：无 client 指令 -->
16
    <StaticProductCard :product="product" />
17

18
    <!-- 可以传递复杂数据 -->
19
    <StaticProductCard :product="{
20
      ...product,
21
      tags: [...product.tags, '推荐', '热销'],
22
    }" />
23

24
    <!-- 静态列表渲染 -->
25
    <div class="product-grid">
26
      {product.relatedProducts.map(relatedProduct => (
27
        <StaticProductCard :product="relatedProduct" />
28
      ))}
29
    </div>
30
  </main>
31
</body>
32
</html>
33

34
<style>
35
.product-page {
36
  max-width: 1200px;
37
  margin: 0 auto;
38
  padding: 2rem;
39
}
40

41
.product-grid {
42
  display: grid;
43
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
44
  gap: 2rem;
45
  margin-top: 3rem;
46
}
47
</style>

3.4 静态组件的限制与最佳实践#

限制：#

无响应性：数据不会响应式更新
无生命周期钩子：onMounted、onUpdated 等不会执行
无事件处理：@click、@input 等事件无效
无动态组件：<component :is> 无法工作

最佳实践：#

1
// 静态组件只用于纯展示
2
// 坏例子：尝试在静态组件中使用交互
3
<button @click="handleClick">点击我</button> // ❌ 不会工作
4

5
// 好例子：只展示信息
6
<div class="info">
7
  <h3>{{ title }}</h3>
8
  <p>{{ description }}</p>
9
</div> // ✅ 完全静态

四、动态 Vue 组件#

4.1 什么是动态 Vue 组件？#

动态 Vue 组件在客户端被激活（hydrate），具有完整的 Vue 功能：

响应式数据
生命周期钩子
事件处理
状态管理
路由（如果集成）

4.2 激活策略#

Astro 提供四种 hydration 策略：

策略	描述	适用场景
`client:load`	立即加载	关键交互组件
`client:idle`	浏览器空闲时加载	非关键交互
`client:visible`	进入视口时加载	懒加载内容
`client:media`	满足媒体查询时加载	响应式组件

4.3 创建动态 Vue 组件#

1
<template>
2
  <div class="interactive-cart" :class="{ 'is-empty': totalItems === 0 }">
3
    <!-- 购物车头部 -->
4
    <div class="cart-header">
5
      <h3>购物车 ({{ totalItems }})</h3>
6
      <button
7
        v-if="totalItems > 0"
8
        @click="clearCart"
9
        class="clear-btn"
10
        aria-label="清空购物车"
11
      >
12
        清空
13
      </button>
14
    </div>
15

16
    <!-- 空状态 -->
17
    <div v-if="totalItems === 0" class="empty-state">
18
      <svg class="empty-icon" viewBox="0 0 24 24">
19
        <path d="M7 18c-1.1 0-1.99.9-1.99 2S5.9 22 7 22s2-.9 2-2-.9-2-2-2zM1 2v2h2l3.6 7.59-1.35 2.45c-.16.28-.25.61-.25.96 0 1.1.9 2 2 2h12v-2H7.42c-.14 0-.25-.11-.25-.25l.03-.12.9-1.63h7.45c.75 0 1.41-.41 1.75-1.03l3.58-6.49c.08-.14.12-.31.12-.48 0-.55-.45-1-1-1H5.21l-.94-2H1zm16 16c-1.1 0-1.99.9-1.99 2s.89 2 1.99 2 2-.9 2-2-.9-2-2-2z"/>
20
      </svg>
21
      <p>购物车是空的</p>
22
      <button @click="goToProducts" class="browse-btn">
23
        浏览商品
24
      </button>
25
    </div>
26

27
    <!-- 购物车商品列表 -->
28
    <div v-else class="cart-items">
29
      <div
30
        v-for="item in cartItems"
31
        :key="item.id"
32
        class="cart-item"
33
      >
34
        <div class="item-info">
35
          <img
36
            :src="item.image"
37
            :alt="item.name"
38
            class="item-image"
39
          >
40
          <div class="item-details">
41
            <h4 class="item-name">{{ item.name }}</h4>
42
            <p class="item-price">¥{{ item.price }}</p>
43
          </div>
44
        </div>
45

46
        <div class="item-controls">
47
          <div class="quantity-control">
48
            <button
49
              @click="decreaseQuantity(item.id)"
50
              :disabled="item.quantity <= 1"
51
              class="qty-btn"
52
            >
53
              −
54
            </button>
55
            <span class="quantity">{{ item.quantity }}</span>
56
            <button
57
              @click="increaseQuantity(item.id)"
58
              class="qty-btn"
59
            >
60
              +
61
            </button>
62
          </div>
63

64
          <button
65
            @click="removeItem(item.id)"
66
            class="remove-btn"
67
            aria-label="删除商品"
68
          >
69
            ×
70
          </button>
71
        </div>
72
      </div>
73
    </div>
74

75
    <!-- 购物车总计 -->
76
    <div v-if="totalItems > 0" class="cart-summary">
77
      <div class="summary-row">
78
        <span>商品总价</span>
79
        <span>¥{{ subtotal }}</span>
80
      </div>
81
      <div class="summary-row">
82
        <span>运费</span>
83
        <span>{{ shippingCost === 0 ? '免费' : `¥${shippingCost}` }}</span>
84
      </div>
85
      <div class="summary-row total">
86
        <span>总计</span>
87
        <span>¥{{ totalPrice }}</span>
88
      </div>
89

90
      <button
91
        @click="checkout"
92
        class="checkout-btn"
93
        :disabled="isCheckingOut"
94
      >
95
        <span v-if="!isCheckingOut">去结算</span>
96
        <span v-else class="loading">处理中...</span>
97
      </button>
98
    </div>
99
  </div>
100
</template>
101

102
<script setup>
103
import { ref, computed, onMounted, onUnmounted } from 'vue';
104
import { useCartStore } from '../../../stores/cart';
105

106
// 使用 Pinia 状态管理
107
const cartStore = useCartStore();
108

109
// 本地状态
110
const isCheckingOut = ref(false);
111

112
// 计算属性
113
const cartItems = computed(() => cartStore.items);
114
const totalItems = computed(() => cartStore.totalItems);
115
const subtotal = computed(() => cartStore.subtotal);
116
const shippingCost = computed(() => cartStore.shippingCost);
117
const totalPrice = computed(() => cartStore.totalPrice);
118

119
// 方法
120
const increaseQuantity = (productId) => {
121
  cartStore.updateQuantity(productId, 1);
122
};
123

124
const decreaseQuantity = (productId) => {
125
  cartStore.updateQuantity(productId, -1);
126
};
127

128
const removeItem = (productId) => {
129
  if (confirm('确定要从购物车删除此商品吗？')) {
130
    cartStore.removeItem(productId);
131
  }
132
};
133

134
const clearCart = () => {
135
  if (confirm('确定要清空购物车吗？')) {
136
    cartStore.clearCart();
137
  }
138
};
139

140
const checkout = async () => {
141
  try {
142
    isCheckingOut.value = true;
143

144
    // 模拟 API 调用
145
    await new Promise(resolve => setTimeout(resolve, 1000));
146

147
    // 实际项目中这里会调用支付接口
148
    alert('订单提交成功！');
149
    cartStore.clearCart();
150
  } catch (error) {
151
    console.error('结算失败:', error);
152
    alert('结算失败，请重试');
153
  } finally {
154
    isCheckingOut.value = false;
155
  }
156
};
157

158
const goToProducts = () => {
159
  // 在实际项目中，这里可能会使用路由跳转
160
  window.location.href = '/products';
161
};
162

163
// 生命周期钩子
164
onMounted(() => {
165
  console.log('购物车组件已挂载');
166

167
  // 监听 storage 变化（多标签页同步）
168
  window.addEventListener('storage', handleStorageChange);
169
});
170

171
onUnmounted(() => {
172
  window.removeEventListener('storage', handleStorageChange);
173
});
174

175
const handleStorageChange = (event) => {
176
  if (event.key === 'cart') {
177
    cartStore.loadFromStorage();
178
  }
179
};
180

181
// 暴露方法供父组件调用（如果需要）
182
defineExpose({
183
  clearCart,
184
  getItemCount: () => totalItems.value,
185
});
186
</script>
187

188
<style scoped>
189
.interactive-cart {
190
  background: white;
191
  border-radius: 12px;
192
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
193
  padding: 1.5rem;
194
  transition: all 0.3s ease;
195
}
196

197
.interactive-cart.is-empty {
198
  text-align: center;
199
  padding: 3rem 1.5rem;
200
}
201

202
.cart-header {
203
  display: flex;
204
  justify-content: space-between;
205
  align-items: center;
206
  margin-bottom: 1.5rem;
207
  padding-bottom: 0.75rem;
208
  border-bottom: 2px solid #f3f4f6;
209
}
210

211
.cart-header h3 {
212
  margin: 0;
213
  color: #1f2937;
214
  font-size: 1.25rem;
215
}
216

217
.clear-btn {
218
  background: none;
219
  border: none;
220
  color: #ef4444;
221
  cursor: pointer;
222
  font-size: 0.875rem;
223
  padding: 0.25rem 0.5rem;
224
  border-radius: 4px;
225
  transition: background-color 0.2s;
226
}
227

228
.clear-btn:hover {
229
  background-color: #fef2f2;
230
}
231

232
.empty-state {
233
  color: #6b7280;
234
}
235

236
.empty-icon {
237
  width: 64px;
238
  height: 64px;
239
  margin: 0 auto 1rem;
240
  fill: #d1d5db;
241
}
242

243
.empty-state p {
244
  margin: 0 0 1.5rem;
245
  font-size: 1.125rem;
246
}
247

248
.browse-btn {
249
  background-color: #3b82f6;
250
  color: white;
251
  border: none;
252
  padding: 0.75rem 1.5rem;
253
  border-radius: 8px;
254
  font-size: 1rem;
255
  cursor: pointer;
256
  transition: background-color 0.2s;
257
}
258

259
.browse-btn:hover {
260
  background-color: #2563eb;
261
}
262

263
.cart-items {
264
  display: flex;
265
  flex-direction: column;
266
  gap: 1rem;
267
  margin-bottom: 2rem;
268
}
269

270
.cart-item {
271
  display: flex;
272
  justify-content: space-between;
273
  align-items: center;
274
  padding: 1rem;
275
  background-color: #f9fafb;
276
  border-radius: 8px;
277
}
278

279
.item-info {
280
  display: flex;
281
  align-items: center;
282
  gap: 1rem;
283
}
284

285
.item-image {
286
  width: 64px;
287
  height: 64px;
288
  border-radius: 8px;
289
  object-fit: cover;
290
}
291

292
.item-details {
293
  display: flex;
294
  flex-direction: column;
295
  gap: 0.25rem;
296
}
297

298
.item-name {
299
  margin: 0;
300
  font-size: 1rem;
301
  font-weight: 600;
302
  color: #1f2937;
303
}
304

305
.item-price {
306
  margin: 0;
307
  color: #ef4444;
308
  font-weight: bold;
309
}
310

311
.item-controls {
312
  display: flex;
313
  align-items: center;
314
  gap: 1rem;
315
}
316

317
.quantity-control {
318
  display: flex;
319
  align-items: center;
320
  gap: 0.5rem;
321
  background: white;
322
  border: 1px solid #d1d5db;
323
  border-radius: 6px;
324
  padding: 0.25rem;
325
}
326

327
.qty-btn {
328
  background: none;
329
  border: none;
330
  width: 24px;
331
  height: 24px;
332
  display: flex;
333
  align-items: center;
334
  justify-content: center;
335
  cursor: pointer;
336
  border-radius: 4px;
337
  color: #4b5563;
338
  font-size: 1rem;
339
}
340

341
.qty-btn:hover:not(:disabled) {
342
  background-color: #f3f4f6;
343
}
344

345
.qty-btn:disabled {
346
  color: #9ca3af;
347
  cursor: not-allowed;
348
}
349

350
.quantity {
351
  min-width: 20px;
352
  text-align: center;
353
  font-weight: 600;
354
}
355

356
.remove-btn {
357
  background: none;
358
  border: none;
359
  width: 32px;
360
  height: 32px;
361
  display: flex;
362
  align-items: center;
363
  justify-content: center;
364
  cursor: pointer;
365
  border-radius: 6px;
366
  color: #9ca3af;
367
  font-size: 1.25rem;
368
}
369

370
.remove-btn:hover {
371
  background-color: #fef2f2;
372
  color: #ef4444;
373
}
374

375
.cart-summary {
376
  border-top: 2px solid #f3f4f6;
377
  padding-top: 1.5rem;
378
}
379

380
.summary-row {
381
  display: flex;
382
  justify-content: space-between;
383
  margin-bottom: 0.75rem;
384
  color: #4b5563;
385
}
386

387
.summary-row.total {
388
  font-size: 1.25rem;
389
  font-weight: bold;
390
  color: #1f2937;
391
  margin-top: 1rem;
392
  padding-top: 1rem;
393
  border-top: 2px solid #e5e7eb;
394
}
395

396
.checkout-btn {
397
  width: 100%;
398
  background-color: #10b981;
399
  color: white;
400
  border: none;
401
  padding: 1rem;
402
  border-radius: 8px;
403
  font-size: 1.125rem;
404
  font-weight: 600;
405
  cursor: pointer;
406
  margin-top: 1.5rem;
407
  transition: background-color 0.2s;
408
}
409

410
.checkout-btn:hover:not(:disabled) {
411
  background-color: #059669;
412
}
413

414
.checkout-btn:disabled {
415
  background-color: #9ca3af;
416
  cursor: not-allowed;
417
}
418

419
.loading {
420
  display: inline-flex;
421
  align-items: center;
422
  justify-content: center;
423
  gap: 0.5rem;
424
}
425

426
.loading::after {
427
  content: '';
428
  width: 12px;
429
  height: 12px;
430
  border: 2px solid white;
431
  border-top-color: transparent;
432
  border-radius: 50%;
433
  animation: spin 1s linear infinite;
434
}
435

436
@keyframes spin {
437
  to { transform: rotate(360deg); }
438
}
439
</style>

4.4 在 Astro 中使用动态 Vue 组件#

1
---
2
import InteractiveCart from '../../components/vue/dynamic/InteractiveCart.vue';
3
import ProductRecommendations from '../../components/vue/dynamic/ProductRecommendations.vue';
4
import CartSummaryStatic from '../../components/astro/CartSummary.astro';
5
import { getCartRecommendations } from '../../api/cart';
6

7
// 获取静态数据
8
const recommendations = await getCartRecommendations();
9

10
// 动态组件的状态（如果需要传递给组件）
11
const cartInitialState = {
12
  // 可以在构建时预加载一些数据
13
  preloadedItems: [],
14
  userDiscount: 0.1, // 10% 折扣
15
};
16
---
17

18
<html lang="zh-CN">
19
<head>
20
  <title>购物车 - 我的商店</title>
21

22
  <!-- 只加载动态组件需要的 CSS -->
23
  <style>
24
    /* 关键 CSS，内联以提高性能 */
25
    .cart-container {
26
      display: grid;
27
      grid-template-columns: 2fr 1fr;
28
      gap: 2rem;
29
      max-width: 1400px;
30
      margin: 0 auto;
31
      padding: 2rem;
32
    }
33

34
    @media (max-width: 1024px) {
35
      .cart-container {
36
        grid-template-columns: 1fr;
37
      }
38
    }
39
  </style>
40
</head>
41
<body>
42
  <main class="cart-container">
43
    <!-- 左侧：动态购物车 -->
44
    <section class="cart-section">
45
      <h1>我的购物车</h1>
46

47
      <!-- 动态 Vue 组件 - 立即激活 -->
48
      <InteractiveCart
49
        client:load
50
        :initial-state="cartInitialState"
51
        :user-discount="0.1"
52
      />
53

54
      <!-- 另一个动态组件 - 懒加载 -->
55
      <ProductRecommendations
56
        client:visible
57
        :products="recommendations"
58
        title="根据购物车推荐"
59
      />
60
    </section>
61

62
    <!-- 右侧：静态摘要 -->
63
    <aside class="sidebar">
64
      <!-- 静态 Astro 组件 -->
65
      <CartSummaryStatic />
66

67
      <!-- 静态 Vue 组件（无交互） -->
68
      <StaticPromotionCard
69
        :promotion="{
70
          code: 'SAVE10',
71
          description: '首次下单立减10%',
72
          validUntil: '2023-12-31',
73
        }"
74
      />
75

76
      <!-- 按需激活的辅助组件 -->
77
      <ShippingCalculator
78
        client:idle
79
        :initial-zip-code="'100000'"
80
      />
81
    </aside>
82
  </main>
83

84
  <!-- 动态组件的样式可以异步加载 -->
85
  <link rel="stylesheet" href="/styles/cart.css" media="print" onload="this.media='all'" />
86

87
  <!-- 只加载必要的 JavaScript -->
88
  <script>
89
    // 页面级的 JavaScript（如果需要）
90
    window.addEventListener('cart-updated', (event) => {
91
      console.log('购物车已更新:', event.detail);
92
      // 可以在这里更新页面其他部分
93
    });
94
  </script>
95
</body>
96
</html>

4.5 动态组件的最佳实践#

1. 按需加载策略#

1
---
2
// 根据组件重要性选择加载策略
3
import CriticalComponent from '../../components/vue/dynamic/CriticalComponent.vue';
4
import SecondaryComponent from '../../components/vue/dynamic/SecondaryComponent.vue';
5
import LazyComponent from '../../components/vue/dynamic/LazyComponent.vue';
6
import ConditionalComponent from '../../components/vue/dynamic/ConditionalComponent.vue';
7
---
8

9
<!-- 关键组件：立即加载 -->
10
<CriticalComponent client:load />
11

12
<!-- 次要组件：空闲时加载 -->
13
<SecondaryComponent client:idle />
14

15
<!-- 大型组件：可见时加载 -->
16
<LazyComponent client:visible />
17

18
<!-- 条件性组件：满足条件时加载 -->
19
<ConditionalComponent client:media="(max-width: 768px)" />

2. Props 传递优化#

1
<!-- Vue 组件中优化 Props 接收 -->
2
<script setup>
3
// 使用 TypeScript 获得更好的类型安全
4
interface Product {
5
  id: string;
6
  name: string;
7
  price: number;
8
}
9

10
interface Props {
11
  // 基本类型
12
  title: string;
13
  count?: number; // 可选参数
14

15
  // 复杂对象
16
  product: Product;
17

18
  // 数组
19
  items: Array<{
20
    id: string;
21
    label: string;
22
  }>;
23

24
  // 函数
25
  onUpdate?: (value: string) => void;
26

27
  // 响应式 props
28
  modelValue?: string;
29
}
30

31
const props = withDefaults(defineProps<Props>(), {
32
  count: 0,
33
  items: () => [],
34
  onUpdate: undefined,
35
});
36

37
// 使用 computed 处理 props
38
const formattedPrice = computed(() => {
39
  return `¥${props.product.price.toLocaleString()}`;
40
});
41
</script>

3. 状态管理集成#

1
// src/stores/cart.js - Pinia 示例
2
import { defineStore } from 'pinia';
3
import { ref, computed } from 'vue';
4

5
export const useCartStore = defineStore('cart', () => {
6
  // 状态
7
  const items = ref([]);
8
  const shippingCost = ref(0);
9

10
  // getters
11
  const totalItems = computed(() => {
12
    return items.value.reduce((sum, item) => sum + item.quantity, 0);
13
  });
14

15
  const subtotal = computed(() => {
16
    return items.value.reduce((sum, item) => sum + (item.price * item.quantity), 0);
17
  });
18

19
  const totalPrice = computed(() => {
20
    return subtotal.value + shippingCost.value;
21
  });
22

23
  // actions
24
  const addItem = (product) => {
25
    const existingItem = items.value.find(item => item.id === product.id);
26

27
    if (existingItem) {
28
      existingItem.quantity += 1;
29
    } else {
30
      items.value.push({
31
        ...product,
32
        quantity: 1,
33
      });
34
    }
35

36
    saveToStorage();
37
  };
38

39
  const removeItem = (productId) => {
40
    items.value = items.value.filter(item => item.id !== productId);
41
    saveToStorage();
42
  };
43

44
  const clearCart = () => {
45
    items.value = [];
46
    saveToStorage();
47
  };
48

49
  // 持久化
50
  const saveToStorage = () => {
51
    if (typeof window !== 'undefined') {
52
      localStorage.setItem('cart', JSON.stringify(items.value));
53
    }
54
  };
55

56
  const loadFromStorage = () => {
57
    if (typeof window !== 'undefined') {
58
      const saved = localStorage.getItem('cart');
59
      if (saved) {
60
        items.value = JSON.parse(saved);
61
      }
62
    }
63
  };
64

65
  return {
66
    items,
67
    shippingCost,
68
    totalItems,
69
    subtotal,
70
    totalPrice,
71
    addItem,
72
    removeItem,
73
    clearCart,
74
    loadFromStorage,
75
  };
76
});

五、混合使用静态与动态组件#

5.1 智能组件模式#

1
<template>
2
  <div
3
    class="smart-product-card"
4
    :class="{ interactive: isInteractive }"
5
    @click="handleClick"
6
  >
7
    <!-- 静态部分 -->
8
    <div class="product-image">
9
      <img
10
        :src="product.image"
11
        :alt="product.name"
12
        loading="lazy"
13
      >
14
    </div>
15

16
    <div class="product-info">
17
      <h3>{{ product.name }}</h3>
18
      <div class="price">¥{{ product.price }}</div>
19
    </div>
20

21
    <!-- 动态部分 -->
22
    <div v-if="isInteractive" class="interactive-actions">
23
      <button
24
        @click.stop="addToCart"
25
        class="add-to-cart-btn"
26
        :disabled="isAdding"
27
      >
28
        <span v-if="!isAdding">加入购物车</span>
29
        <span v-else class="loading">添加中...</span>
30
      </button>
31

32
      <button
33
        @click.stop="toggleWishlist"
34
        class="wishlist-btn"
35
        :class="{ active: isInWishlist }"
36
        aria-label="收藏"
37
      >
38
        ♡
39
      </button>
40
    </div>
41

42
    <!-- 静态的收藏指示器 -->
43
    <div v-else class="static-indicator">
44
      <div v-if="product.isPopular" class="badge popular">
45
        热门
46
      </div>
47
      <div v-if="product.discount" class="badge discount">
48
        -{{ product.discount }}%
49
      </div>
50
    </div>
51
  </div>
52
</template>
53

54
<script setup>
55
import { ref, computed } from 'vue';
56

57
const props = defineProps({
58
  product: {
59
    type: Object,
60
    required: true,
61
  },
62
  // 控制是否为交互模式
63
  interactive: {
64
    type: Boolean,
65
    default: false,
66
  },
67
});
68

69
// 只有在交互模式下才需要这些
70
const isAdding = ref(false);
71
const isInWishlist = ref(false);
72

73
const isInteractive = computed(() => {
74
  return props.interactive && typeof window !== 'undefined';
75
});
76

77
// 方法只在交互模式下执行
78
const addToCart = async () => {
79
  if (!isInteractive.value) return;
80

81
  isAdding.value = true;
82
  try {
83
    // 模拟 API 调用
84
    await new Promise(resolve => setTimeout(resolve, 500));
85
    console.log('Added to cart:', props.product.id);
86
  } finally {
87
    isAdding.value = false;
88
  }
89
};
90

91
const toggleWishlist = () => {
92
  if (!isInteractive.value) return;
93
  isInWishlist.value = !isInWishlist.value;
94
};
95

96
const handleClick = () => {
97
  // 在静态模式下，点击跳转到详情页
98
  if (!isInteractive.value) {
99
    window.location.href = `/products/${props.product.id}`;
100
  }
101
};
102
</script>
103

104
<style scoped>
105
.smart-product-card {
106
  border: 1px solid #e5e7eb;
107
  border-radius: 12px;
108
  overflow: hidden;
109
  transition: all 0.3s ease;
110
  cursor: pointer;
111
}
112

113
.smart-product-card:hover {
114
  border-color: #3b82f6;
115
  box-shadow: 0 10px 25px -5px rgba(59, 130, 246, 0.1);
116
}
117

118
.product-image {
119
  aspect-ratio: 1/1;
120
  overflow: hidden;
121
}
122

123
.product-image img {
124
  width: 100%;
125
  height: 100%;
126
  object-fit: cover;
127
}
128

129
.product-info {
130
  padding: 1rem;
131
}
132

133
.product-info h3 {
134
  margin: 0 0 0.5rem;
135
  font-size: 1.125rem;
136
  font-weight: 600;
137
}
138

139
.price {
140
  color: #ef4444;
141
  font-size: 1.25rem;
142
  font-weight: bold;
143
}
144

145
/* 交互模式样式 */
146
.interactive-actions {
147
  padding: 0 1rem 1rem;
148
  display: flex;
149
  gap: 0.5rem;
150
}
151

152
.add-to-cart-btn {
153
  flex: 1;
154
  background-color: #3b82f6;
155
  color: white;
156
  border: none;
157
  padding: 0.75rem;
158
  border-radius: 8px;
159
  font-size: 1rem;
160
  cursor: pointer;
161
  transition: background-color 0.2s;
162
}
163

164
.add-to-cart-btn:hover:not(:disabled) {
165
  background-color: #2563eb;
166
}
167

168
.add-to-cart-btn:disabled {
169
  background-color: #9ca3af;
170
  cursor: not-allowed;
171
}
172

173
.wishlist-btn {
174
  width: 48px;
175
  background: white;
176
  border: 2px solid #d1d5db;
177
  border-radius: 8px;
178
  font-size: 1.25rem;
179
  cursor: pointer;
180
  transition: all 0.2s;
181
}
182

183
.wishlist-btn:hover {
184
  border-color: #ef4444;
185
  color: #ef4444;
186
}
187

188
.wishlist-btn.active {
189
  background-color: #fef2f2;
190
  border-color: #ef4444;
191
  color: #ef4444;
192
}
193

194
/* 静态模式样式 */
195
.static-indicator {
196
  padding: 0 1rem 1rem;
197
  display: flex;
198
  gap: 0.5rem;
199
}
200

201
.badge {
202
  padding: 0.25rem 0.5rem;
203
  border-radius: 4px;
204
  font-size: 0.75rem;
205
  font-weight: 600;
206
}
207

208
.badge.popular {
209
  background-color: #fef3c7;
210
  color: #92400e;
211
}
212

213
.badge.discount {
214
  background-color: #fef2f2;
215
  color: #ef4444;
216
}
217

218
.loading {
219
  display: inline-flex;
220
  align-items: center;
221
  justify-content: center;
222
  gap: 0.5rem;
223
}
224

225
.loading::after {
226
  content: '';
227
  width: 12px;
228
  height: 12px;
229
  border: 2px solid white;
230
  border-top-color: transparent;
231
  border-radius: 50%;
232
  animation: spin 1s linear infinite;
233
}
234

235
@keyframes spin {
236
  to { transform: rotate(360deg); }
237
}
238
</style>

5.2 在 Astro 中智能使用#

1
---
2
import SmartProductCard from '../../components/vue/SmartProductCard.vue';
3
import InteractiveFilters from '../../components/vue/dynamic/InteractiveFilters.vue';
4
import { getProducts } from '../../api/products';
5

6
// 获取所有产品
7
const products = await getProducts();
8
---
9

10
<html lang="zh-CN">
11
<head>
12
  <title>产品列表 - 我的商店</title>
13
</head>
14
<body>
15
  <div class="products-page">
16
    <!-- 动态过滤器 -->
17
    <InteractiveFilters
18
      client:load
19
      :initial-category="Astro.url.searchParams.get('category')"
20
    />
21

22
    <!-- 产品网格 -->
23
    <div class="products-grid">
24
      {products.map(product => {
25
        // 判断哪些产品需要交互
26
        const isFeatured = product.tags.includes('featured');
27
        const hasStock = product.stock > 0;
28

29
        return (
30
          <SmartProductCard
31
            // 只有特色且有库存的产品才启用交互
32
            interactive={isFeatured && hasStock}
33
            client={isFeatured ? 'load' : 'idle'}
34
            :product="product"
35
          />
36
        );
37
      })}
38
    </div>
39
  </div>
40

41
  <script>
42
    // 智能加载更多交互
43
    document.addEventListener('DOMContentLoaded', () => {
44
      const observer = new IntersectionObserver((entries) => {
45
        entries.forEach(entry => {
46
          if (entry.isIntersecting) {
47
            const card = entry.target;
48
            // 当卡片进入视口时，激活其交互性
49
            card.setAttribute('data-interactive', 'true');
50
          }
51
        });
52
      });
53

54
      document.querySelectorAll('.smart-product-card:not([interactive])')
55
        .forEach(card => observer.observe(card));
56
    });
57
  </script>
58
</body>
59
</html>

六、高级集成技巧#

6.1 Vue Router 集成#

1
// 在 Astro 中集成 Vue Router
2
<template>
3
  <RouterView />
4
</template>
5

6
<script setup>
7
import { createRouter, createWebHistory } from 'vue-router';
8

9
// 定义路由
10
const routes = [
11
  {
12
    path: '/vue-app',
13
    component: () => import('./VueApp.vue'),
14
    children: [
15
      {
16
        path: 'dashboard',
17
        component: () => import('./Dashboard.vue'),
18
      },
19
      {
20
        path: 'profile',
21
        component: () => import('./Profile.vue'),
22
      },
23
    ],
24
  },
25
];
26

27
// 创建路由实例
28
const router = createRouter({
29
  history: createWebHistory(),
30
  routes,
31
});
32
</script>

1
---
2
// 在 Astro 页面中使用 Vue Router
3
import AppRouter from '../components/vue/AppRouter.vue';
4
---
5

6
<!-- 独立的路由应用区域 -->
7
<AppRouter client:load />

6.2 Vue 插件集成#

1
import { createPinia } from 'pinia';
2
import VueLazyLoad from 'vue3-lazyload';
3
import Toast from 'vue-toastification';
4
import 'vue-toastification/dist/index.css';
5

6
// 创建插件实例
7
const pinia = createPinia();
8

9
export const vuePlugins = [
10
  // 状态管理
11
  [pinia],
12

13
  // 懒加载
14
  [VueLazyLoad, {
15
    loading: '/images/loading.gif',
16
    error: '/images/error.png',
17
  }],
18

19
  // 通知
20
  [Toast, {
21
    position: 'top-right',
22
    timeout: 3000,
23
    closeOnClick: true,
24
    pauseOnFocusLoss: true,
25
    pauseOnHover: true,
26
  }],
27
];

1
import { defineConfig } from 'astro/config';
2
import vue from '@astrojs/vue';
3
import { vuePlugins } from './src/plugins/vue-plugins';
4

5
export default defineConfig({
6
  integrations: [vue({
7
    appEntrypoint: '/src/vue-app',
8
  })],
9
});

6.3 服务端渲染 (SSR) 支持#

1
import { defineConfig } from 'astro/config';
2
import vue from '@astrojs/vue';
3

4
export default defineConfig({
5
  output: 'server', // 启用 SSR
6
  integrations: [vue()],
7
});
8

9
// 在 Vue 组件中处理 SSR
10
export default {
11
  name: 'SSRComponent',
12
  async setup() {
13
    // 在服务器端和客户端都可以执行的逻辑
14
    const { data } = await useAsyncData(() => {
15
      return $fetch('/api/data');
16
    });
17

18
    return { data };
19
  },
20
};

七、性能优化与最佳实践#

7.1 性能监控#

1
<template>
2
  <!-- 性能监控组件 -->
3
</template>
4

5
<script setup>
6
import { onMounted } from 'vue';
7

8
onMounted(() => {
9
  // 监控组件加载性能
10
  const timing = window.performance.timing;
11
  const loadTime = timing.domContentLoadedEventEnd - timing.navigationStart;
12

13
  console.log(`Vue 组件加载时间: ${loadTime}ms`);
14

15
  // 发送性能指标
16
  if (typeof window.gtag !== 'undefined') {
17
    window.gtag('event', 'vue_component_load', {
18
      event_category: 'Performance',
19
      event_label: 'Vue Component',
20
      value: loadTime,
21
    });
22
  }
23
});
24
</script>

7.2 代码分割#

1
// 动态导入大型组件
2
const HeavyComponent = defineAsyncComponent(() =>
3
  import('./HeavyComponent.vue')
4
);
5

6
// 在 Astro 中使用
7
<HeavyComponent client:visible />

7.3 内存管理#

1
<script setup>
2
import { onUnmounted } from 'vue';
3

4
// 清理事件监听器
5
const eventListeners = [];
6

7
onMounted(() => {
8
  const handleResize = () => {
9
    console.log('Window resized');
10
  };
11

12
  window.addEventListener('resize', handleResize);
13
  eventListeners.push(() => {
14
    window.removeEventListener('resize', handleResize);
15
  });
16
});
17

18
onUnmounted(() => {
19
  // 清理所有监听器
20
  eventListeners.forEach(cleanup => cleanup());
21
});
22
</script>

八、常见问题与解决方案#

8.1 水合不匹配错误#

问题: 服务器渲染的 HTML 与客户端 Vue 应用不匹配。

解决方案:

1
<script setup>
2
// 只在客户端执行的代码
3
import { onMounted } from 'vue';
4

5
onMounted(() => {
6
  // 客户端特定的逻辑
7
  if (typeof window !== 'undefined') {
8
    // 访问 window 对象
9
  }
10
});
11

12
// 使用 v-if 控制只在客户端渲染的内容
13
const isClient = typeof window !== 'undefined';
14
</script>
15

16
<template>
17
  <div>
18
    <!-- 服务器和客户端都渲染 -->
19
    <div class="static-content">{{ serverData }}</div>
20

21
    <!-- 只在客户端渲染 -->
22
    <div v-if="isClient" class="client-only">
23
      {{ clientData }}
24
    </div>
25
  </div>
26
</template>

8.2 样式冲突#

解决方案:

1
<template>
2
  <div class="vue-component">
3
    <!-- 使用作用域样式 -->
4
  </div>
5
</template>
6

7
<style scoped>
8
/* 作用域样式 */
9
.vue-component {
10
  /* 组件样式 */
11
}
12
</style>
13

14
<!-- 或者使用 CSS Modules -->
15
<style module>
16
.container {
17
  background: white;
18
}
19
</style>

8.3 第三方库集成#

1
<script setup>
2
// 确保第三方库只在客户端使用
3
let SomeLibrary;
4
if (typeof window !== 'undefined') {
5
  SomeLibrary = (await import('some-library')).default;
6
}
7

8
const useLibrary = () => {
9
  if (SomeLibrary) {
10
    return new SomeLibrary();
11
  }
12
  return null;
13
};
14
</script>

九、总结与推荐架构#

9.1 推荐架构模式#

1
推荐架构：
2
1. 使用静态 Vue 组件展示内容
3
2. 对关键交互使用动态组件 + client:load
4
3. 对次要交互使用动态组件 + client:idle 或 client:visible
5
4. 使用状态管理共享复杂状态
6
5. 按需加载大型组件

9.2 决策流程图#

1
是否需要在客户端交互？
2
├── 否 → 使用静态 Vue 组件
3
└── 是 → 判断交互重要性
4
    ├── 关键交互（如购物车、表单） → client:load
5
    ├── 次要交互（如点赞、评论） → client:idle
6
    ├── 懒加载内容（如图片库） → client:visible
7
    └── 条件性交互（如移动端菜单） → client:media

9.3 性能检查清单#

静态内容使用静态 Vue 组件
动态组件使用合适的 hydration 策略
大型组件使用动态导入
避免在静态组件中使用客户端 API
使用 CSS 作用域防止样式冲突
监控组件加载性能
清理事件监听器防止内存泄漏

十、学习资源#

官方文档#

工具与库#

Pinia - Vue 状态管理
VueUse - Vue 组合式工具集
Vite - 构建工具（Astro 底层使用）

性能工具#

通过合理使用静态和动态 Vue 组件，你可以在 Astro 中构建出既快速又富有交互性的现代 Web 应用。记住：从静态开始，按需添加交互，这是 Astro 哲学的核心。

Lovely March7th!

在 Astro 中集成 Vue.js

在 Astro 中集成 Vue.js：静态与动态组件的完整指南#

一、Astro 与 Vue.js 集成概览#

1.1 集成优势#

1.2 两种 Vue 组件模式#

二、基础配置与安装#

2.1 安装依赖#

2.2 配置 Astro#

2.3 项目结构建议#

三、静态 Vue 组件#

3.1 什么是静态 Vue 组件？#

3.2 创建静态 Vue 组件#

3.3 在 Astro 中使用静态 Vue 组件#

3.4 静态组件的限制与最佳实践#

限制：#

最佳实践：#

四、动态 Vue 组件#

4.1 什么是动态 Vue 组件？#

4.2 激活策略#

4.3 创建动态 Vue 组件#

4.4 在 Astro 中使用动态 Vue 组件#

4.5 动态组件的最佳实践#

1. 按需加载策略#

2. Props 传递优化#

3. 状态管理集成#

五、混合使用静态与动态组件#

5.1 智能组件模式#

5.2 在 Astro 中智能使用#

六、高级集成技巧#

6.1 Vue Router 集成#

6.2 Vue 插件集成#

6.3 服务端渲染 (SSR) 支持#

七、性能优化与最佳实践#

7.1 性能监控#

7.2 代码分割#

7.3 内存管理#

八、常见问题与解决方案#

8.1 水合不匹配错误#

8.2 样式冲突#

8.3 第三方库集成#

九、总结与推荐架构#

9.1 推荐架构模式#

9.2 决策流程图#

9.3 性能检查清单#

十、学习资源#

官方文档#

工具与库#

性能工具#

赞助支持

目录