feat: 更新 Vite 配置，优化资源管理和背景图像处理

2025-09-14 20:44:41 +08:00
1 parent 66842e9d58
commit 02ddfd0c07
@@ -0,0 +1,167 @@
+# 图片路径构建后访问解决方案
+
+## 问题描述
+
+在Vue 3 + Vite + TypeScript项目中，图片资源在开发环境正常显示，但构建后无法正常访问。主要问题包括：
+
+1. CSS中的相对路径 `url('../../assets/images/xxx.png')` 在构建后无法正确解析
+2. 动态生成的图片路径无法被Vite静态分析，导致图片未被包含在构建中
+3. 环境变量判断逻辑不正确
+
+## 解决方案
+
+### 1. 使用 `import.meta.glob` 静态导入所有图片
+
+```typescript
+// src/utils/index.ts
+const imageModules = import.meta.glob('../assets/images/**/*.{png,jpg,jpeg,gif,svg,webp}', {
+  eager: true
+})
+
+export const getStaticImage = (path: string) => {
+  try {
+    const imagePath =
+      path.endsWith('.png') ||
+      path.endsWith('.jpg') ||
+      path.endsWith('.jpeg') ||
+      path.endsWith('.gif') ||
+      path.endsWith('.svg') ||
+      path.endsWith('.webp')
+        ? `../assets/images/${path}`
+        : `../assets/images/${path}.png`
+
+    const module = imageModules[imagePath]
+    if (module && typeof module === 'object' && 'default' in module) {
+      return module.default as string
+    }
+
+    return new URL(imagePath, import.meta.url).href
+  } catch (error) {
+    console.error('Failed to load image:', path, error)
+    return ''
+  }
+}
+```
+
+### 2. 修复CSS中的图片路径
+
+**之前（错误）：**
+
+```css
+.guide-panel {
+  background-image: url('../../assets/images/components/box.png');
+}
+```
+
+**之后（正确）：**
+
+```vue
+<template>
+  <div class="guide-panel" :style="{ backgroundImage: getBackgroundImage('components/box') }">
+</template>
+
+<script setup>
+import { getBackgroundImage } from '@/utils'
+</script>
+```
+
+### 3. 优化Vite构建配置
+
+```typescript
+// vite.config.ts
+export default defineConfig(({ mode }) => {
+  return {
+    // ... 其他配置
+    build: {
+      assetsDir: 'assets',
+      rollupOptions: {
+        output: {
+          assetFileNames: assetInfo => {
+            if (/\.(png|jpe?g|gif|svg|webp)$/i.test(assetInfo.name || '')) {
+              return `assets/images/[name]-[hash][extname]`
+            }
+            return `assets/[name]-[hash][extname]`
+          }
+        }
+      }
+    }
+  }
+})
+```
+
+## 关键改进点
+
+### 1. 静态分析支持
+
+- 使用 `import.meta.glob` 确保Vite能够静态分析所有图片资源
+- 所有图片在构建时被正确包含和处理
+
+### 2. 路径统一管理
+
+- 通过 `getStaticImage` 函数统一管理图片路径
+- 支持带扩展名和不带扩展名的路径
+- 提供错误处理和回退机制
+
+### 3. 构建优化
+
+- 图片资源统一放置在 `assets/images/` 目录
+- 文件名包含hash值，支持缓存优化
+- 构建后路径结构清晰
+
+## 使用方式
+
+### 在组件中使用图片
+
+```vue
+<template>
+  <!-- 方式1：直接使用 -->
+  <img :src="getStaticImage('components/person')" alt="人物" />
+
+  <!-- 方式2：作为背景图片 -->
+  <div :style="{ backgroundImage: getBackgroundImage('home/bg') }"></div>
+
+  <!-- 方式3：通过ImgButton组件 -->
+  <ImgButton :image="IMAGE_PATHS.BUTTONS.CONTINUE" />
+</template>
+
+<script setup>
+import { getStaticImage, getBackgroundImage, IMAGE_PATHS } from '@/utils'
+</script>
+```
+
+### 预定义图片路径常量
+
+```typescript
+export const IMAGE_PATHS = {
+  HOME_BG: 'home/guide/bg',
+  ACTION_BG: 'home/action/bg',
+  GUIDE_PERSON: 'components/person',
+  BUTTONS: {
+    CONTINUE: 'components/continue',
+    ESCAPE: 'components/escape'
+  }
+} as const
+```
+
+## 验证结果
+
+构建后验证：
+
+- ✅ 所有图片资源正确包含在 `dist/assets/images/` 目录
+- ✅ 图片路径在构建后正确解析
+- ✅ 预览服务器中图片正常访问
+- ✅ 支持hash文件名，便于缓存管理
+
+## 注意事项
+
+1. **不要将图片放在 `public` 目录**：这会导致图片不被编译和优化
+2. **使用统一的图片管理函数**：避免直接使用相对路径
+3. **确保图片文件存在**：构建时会检查所有引用的图片
+4. **支持多种图片格式**：png, jpg, jpeg, gif, svg, webp
+
+## 相关文件
+
+- 图片处理工具：`src/utils/index.ts`
+- Vite配置：`vite.config.ts`
+- 组件示例：`src/components/Guide/GuideDragon.vue`
+- 按钮组件：`src/components/Button/ImgButton.vue`