Laravel/Vue3/Vite等栈中unplugin-auto-import报ref未定义求助

针对你在Laravel/Vue3/Vite/InertiaJS+SSR/Typescript/Pinia栈里遇到的自动导入失效问题，分享几个我踩过坑后验证有效的配置要点：

1. 补全Vite插件关键配置 #

你的基础配置缺少适配Inertia SSR的核心项，需确保插件覆盖客户端和服务端编译流程：

// vite.config.ts
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';
import AutoImport from 'unplugin-auto-import/vite';

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.ts',
            ssr: 'resources/js/ssr.ts', // 必须明确指定SSR入口
            refresh: true,
        }),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
        AutoImport({
            imports: [
                'vue',
                'pinia' // 若用Pinia，可一并自动导入defineStore等API
            ],
            dts: 'resources/js/auto-imports.d.ts', // 显式指定类型文件路径，避免SSR找不到
            vueTemplate: true, // 支持Vue模板中自动导入API
            // 覆盖所有需要自动导入的文件类型
            include: [
                /\.[tj]sx?$/,
                /\.vue$/, /\.vue\?vue/,
                /\.md$/,
            ],
        }),
    ],
    ssr: {
        noExternal: ['@inertiajs/vue3'], // 避免SSR时外部依赖处理异常
    },
});

2. 修正TypeScript配置细节 #

确保tsconfig.app.json（或根目录tsconfig.json）正确关联自动生成的类型文件，同时开启必要编译选项：

{
    "compilerOptions": {
        "target": "ESNext",
        "module": "ESNext",
        "moduleResolution": "node",
        "strict": true,
        "jsx": "preserve",
        "sourceMap": true,
        "resolveJsonModule": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "lib": ["ESNext", "DOM", "DOM.Iterable"],
        "types": ["vite/client", "node"],
        "allowSyntheticDefaultImports": true // 允许隐式类型导入
    },
    "include": [
        "resources/js/**/*",
        "resources/js/auto-imports.d.ts" // 路径要和vite配置中指定的一致
    ],
    "exclude": ["node_modules", "public"]
}

3. 清理缓存并重启服务 #

Laravel和Vite的缓存可能导致配置不生效，执行以下命令重置：

# 清除Laravel缓存
php artisan cache:clear
php artisan view:clear

# 清除Vite缓存
rm -rf node_modules/.vite
rm -rf public/build

# 重启开发服务
npm run dev

4. 验证自动导入生效状态 #

检查指定路径下的auto-imports.d.ts，确认包含ref等API的全局声明：

// auto-imports.d.ts
/* eslint-disable */
/* prettier-ignore */
// @ts-nocheck
export {}
declare global {
  const ref: typeof import('vue')['ref'];
  const reactive: typeof import('vue')['reactive'];
  // ...其他自动导入的Vue/Pinia API
}

如果仍有ESLint报错，可在.eslintrc.js中添加全局变量声明：

module.exports = {
    globals: {
        ref: 'readonly',
        reactive: 'readonly',
        // 其他自动导入的API
    },
};

内容的提问来源于stack exchange，提问作者Chris at Keddy Digital