基于Nuxt 3与AI大模型的ATS简历智能匹配系统开发实战

1. 项目概述：一个AI驱动的ATS简历扫描器

最近在做一个招聘相关的项目，需要快速筛选大量简历，手动看PDF看到眼花缭乱。正好看到GitHub上有个叫ats-scanner的项目，作者是alessandrror。这个工具的核心思路挺有意思：它不是一个简单的PDF解析器，而是一个结合了AI的“简历扫描仪”，专门用来评估一份简历与某个特定职位描述（Job Description, JD）的匹配度。

简单来说，你给它一份简历（PDF格式）和一个职位描述（文本），它就能调用AI模型（比如Gemini）来分析简历内容，然后生成一份详细的匹配度报告。报告里会列出简历中与JD匹配的技能、经验，也会指出缺失的部分，甚至给出改进建议。这对于招聘官快速筛选候选人，或者求职者自我优化简历，都很有帮助。

项目本身是一个基于Nuxt 3构建的Web应用，前端用Vue 3和Nuxt UI，后端逻辑跑在Node.js环境里，用了Bun作为运行时和包管理器。技术栈选型很现代：TypeScript保证类型安全，Tailwind CSS做样式，PDF.js来解析PDF，最后可以一键部署到Vercel。整个工具的设计目标是轻量、快速、开箱即用。

2. 核心功能与设计思路拆解

2.1 解决什么痛点？

传统的简历筛选要么靠人力，费时费力且主观性强；要么靠一些简单的关键词匹配工具，但缺乏对上下文和语义的理解。比如，JD要求“有团队管理经验”，简历里写的是“带领过5人小组完成项目”，简单的关键词匹配可能抓不到“带领”和“团队管理”之间的关联。而AI，特别是大语言模型（LLM），在这方面有天然优势。

ats-scanner的设计思路就是把人从初筛的重复劳动中解放出来，用AI来做第一轮的“智能匹配”。它不只是找关键词，而是尝试理解JD和简历背后的“意图”和“能力描述”，从而给出一个更接近人类判断的评估结果。

2.2 技术架构选型考量

为什么用这套技术栈？我们来拆解一下：

1. Nuxt 3 + Vue 3：作为全栈框架，Nuxt 3提供了服务端渲染（SSR）、API路由、文件系统路由等开箱即用的能力。这意味着我们可以在同一个项目中，轻松地构建前端页面和处理后端PDF解析、AI API调用等逻辑。对于这样一个前后端交互密集的工具，全栈框架比分离的前端+后端API项目更简洁高效。Vue 3的响应式和组合式API也让状态管理变得清晰。

2. Bun：替代传统的Node.js或npm/yarn。Bun的优势在于极快的启动速度和包安装速度。对于开发阶段需要频繁重启服务器、安装依赖的场景，Bun能显著提升体验。项目中的bun install,bun dev,bun build命令都得益于此。

3. TypeScript：在涉及PDF解析数据结构、AI API请求/响应格式时，类型系统能极大减少运行时错误，提升代码可维护性。尤其是在定义“匹配报告”这种复杂对象时，TypeScript的接口（Interface）非常有用。

4. Tailwind CSS + Nuxt UI：为了快速构建一个美观且可用的界面。Nuxt UI是一套基于Tailwind的Vue组件库，提供了按钮、卡片、表单、模态框等现成组件，让开发者能专注于业务逻辑而非样式细节。这对于需要快速验证想法的工具类项目至关重要。

5. pdfjs-dist：这是Mozilla官方PDF.js库的预构建版本，专门用于Node.js或浏览器环境。用它来解析PDF文件，提取文本内容，是后续AI分析的基础。选择它是因为其可靠性、活跃的社区以及处理复杂PDF格式的能力。

6. AI模型集成（Gemini）：项目示例中使用了Google的Gemini API。选择Gemini或其他LLM（如OpenAI的GPT）的考量点在于：API的易用性、成本、上下文长度以及对中文等语言的支持程度。工具本身应该设计成可配置的，方便用户切换不同的AI后端。

7. Vercel：作为部署平台，Vercel对Nuxt项目有原生的一键部署支持，并且边缘网络能保证全球访问速度。对于这种可能面向国际用户的工具，部署体验和访问性能很重要。

注意：这个项目模板（nuxt-ui-templates/starter）只是一个起点。ats-scanner的具体实现，比如PDF解析逻辑、AI提示词工程、报告生成算法，需要在这个模板基础上进行深度开发。模板提供了项目骨架和基础UI，而核心价值在于我们填充进去的业务逻辑。

3. 从模板到实战：搭建ATS扫描器核心

3.1 环境准备与项目初始化

首先，我们需要基于官方模板创建一个新项目。按照README的指引，最快捷的方式是使用以下命令：

npm create nuxt@latest -- -t github:nuxt-ui-templates/starter

这个命令会调用create-nuxt工具，从指定的GitHub模板仓库拉取代码并初始化项目。过程中会询问项目名称、包管理器（选择Bun）等基本信息。初始化完成后，进入项目目录并安装依赖：

cd your-project-name bun install

依赖安装完成后，可以尝试运行开发服务器：

bun dev

如果一切顺利，浏览器打开http://localhost:3000，你会看到一个干净的Nuxt UI starter页面。这证明基础环境已经搭建成功。

3.2 核心依赖安装与配置

接下来，我们需要安装ats-scanner功能相关的核心依赖。

bun add pdfjs-dist bun add -D @types/pdfjs-dist

pdfjs-dist用于解析PDF，@types/pdfjs-dist是它的TypeScript类型定义文件，方便我们编码。

对于AI部分，以集成Google Gemini为例，需要安装其官方SDK：

bun add @google/generative-ai

然后，我们需要在项目中配置环境变量来存储敏感的API密钥。在项目根目录创建.env文件：

# .env NUXT_GEMINI_API_KEY=你的_Google_AI_Studio_API_密钥

重要提示：永远不要将API密钥硬编码在代码中或提交到版本控制系统（如Git）。.env文件应该被添加到.gitignore中。在Nuxt 3中，我们可以通过runtimeConfig来安全地使用这些环境变量。在nuxt.config.ts中配置：

// nuxt.config.ts export default defineNuxtConfig({ // ... 其他配置 runtimeConfig: { geminiApiKey: process.env.NUXT_GEMINI_API_KEY, // 其他运行时配置 public: { // 这里放置需要暴露给前端的配置 } } })

这样，在服务端代码中，我们就可以通过useRuntimeConfig()来获取geminiApiKey。

3.3 项目结构规划

一个清晰的项目结构有助于维护。在模板基础上，我们可能需要创建以下目录和文件：

server/ api/ scan.post.ts # 处理简历扫描的API端点 utils/ pdfParser.ts # PDF解析工具函数 aiAnalyzer.ts # AI分析核心逻辑 components/ ResumeUploader.vue # 简历上传组件 JobDescriptionInput.vue # JD输入组件 ScanReport.vue # 报告展示组件 pages/ index.vue # 主页面，集成上传、输入和触发扫描 app.vue # 应用根组件，布局定义

这种结构将不同职责的代码分离，使得server/api下的文件专注于处理HTTP请求和响应，utils下的文件是纯逻辑函数，components是可复用的UI部件。

4. 核心模块实现详解

4.1 PDF解析模块实现

PDF解析是整个流程的第一步，也是最容易出问题的一环。我们使用pdfjs-dist来提取PDF中的文本。

// utils/pdfParser.ts import * as pdfjsLib from 'pdfjs-dist'; // 注意：在Node环境下，需要设置worker。这里我们使用内置的PDF.js worker。 pdfjsLib.GlobalWorkerOptions.workerSrc = `//cdnjs.cloudflare.com/ajax/libs/pdf.js/${pdfjsLib.version}/pdf.worker.min.js`; export async function extractTextFromPDF(file: File): Promise<string> { // 1. 将File对象转换为ArrayBuffer const arrayBuffer = await file.arrayBuffer(); // 2. 加载PDF文档 const loadingTask = pdfjsLib.getDocument({ data: arrayBuffer }); const pdf = await loadingTask.promise; let fullText = ''; // 3. 遍历每一页，提取文本 for (let pageNum = 1; pageNum <= pdf.numPages; pageNum++) { const page = await pdf.getPage(pageNum); const textContent = await page.getTextContent(); // 4. 将文本项拼接成字符串 const pageText = textContent.items .map((item: any) => item.str) .join(' '); fullText += pageText + '\n\n'; // 用空行分隔不同页 } // 5. 清理文本：移除多余空格、换行，但保留基本段落结构 const cleanedText = fullText .replace(/\s+/g, ' ') // 将多个空白字符（包括换行）替换为单个空格 .trim(); return cleanedText; }

实操心得与避坑指南：

• Worker路径问题：在浏览器环境中，PDF.js需要Web Worker来执行繁重的解析任务。上述代码使用了CDN上的worker。如果你构建的项目需要离线使用或对CDN有顾虑，可以考虑将worker文件打包进项目，并指向正确的本地路径。
• 复杂格式处理：有些简历是扫描件（图片型PDF），getTextContent()可能提取不出文字。对于生产环境，需要考虑集成OCR（光学字符识别）功能，比如使用Tesseract.js，但这会大大增加复杂性和处理时间。
• 性能考量：对于几十页的简历，逐页解析可能会阻塞主线程。可以考虑使用pdf.getPage的并行处理，或者在后端（Node.js）进行解析，避免影响前端用户体验。
• 编码问题：遇到中文或其他非拉丁字符集时，确保文本提取后编码正确。如果出现乱码，可能需要检查PDF的字体嵌入情况。

4.2 AI分析引擎构建

这是工具的大脑。我们需要设计一个有效的提示词（Prompt），让AI理解我们的任务：对比简历和JD，并结构化地输出评估结果。

// utils/aiAnalyzer.ts import { GoogleGenerativeAI } from '@google/generative-ai'; // 从运行时配置获取API密钥 const config = useRuntimeConfig(); const genAI = new GoogleGenerativeAI(config.geminiApiKey); // 选择模型，例如 Gemini 1.5 Flash 平衡了速度与性能 const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' }); export interface ATSAnalysisResult { overallScore: number; // 总体匹配度分数 (0-100) matchedSkills: Array<{ skill: string; evidence: string; relevance: 'high' | 'medium' | 'low' }>; missingSkills: string[]; experienceGap?: { // 经验差距分析 required: string; candidateHas: string; suggestion: string; }; summary: string; // 总体评价摘要 suggestions: string[]; // 改进建议 } export async function analyzeResumeWithAI(resumeText: string, jobDescription: string): Promise<ATSAnalysisResult> { const prompt = ` 你是一个专业的招聘顾问和ATS（求职者追踪系统）专家。请严格遵循以下步骤分析一份简历与职位描述的匹配度。 职位描述： """ ${jobDescription} """ 候选人简历文本： """ ${resumeText} """ 请按照以下JSON格式输出你的分析结果，不要输出任何其他解释性文字： { "overallScore": [一个0到100的整数，代表总体匹配度], "matchedSkills": [ { "skill": "[与JD匹配的具体技能名称]", "evidence": "[从简历中摘录的证明该技能的原话]", "relevance": "[high/medium/low，表示该技能对职位的重要程度]" } // ... 更多匹配技能 ], "missingSkills": ["[JD要求但简历中明显缺失的技能1]", "[技能2]", ...], "experienceGap": { "required": "[JD中明确要求的、候选人可能不足的关键经验]", "candidateHas": "[候选人实际相关的经验描述]", "suggestion": "[如何弥补该经验差距的具体建议]" }, "summary": "[一段话的总体评价，突出核心优势和主要短板]", "suggestions": ["[具体的简历优化建议1]", "[建议2]", ...] } 请确保分析基于提供的文本，客观、具体。对于匹配的技能，必须提供简历中的证据。`; try { const result = await model.generateContent(prompt); const response = await result.response; const text = response.text(); // AI返回的文本可能包含markdown代码块标记，需要清理 const jsonString = text.replace(/```json\n?|\n?```/g, '').trim(); const analysis: ATSAnalysisResult = JSON.parse(jsonString); return analysis; } catch (error) { console.error('AI分析失败:', error); // 返回一个默认的错误结构或抛出异常，由上层处理 throw new Error('简历分析服务暂时不可用，请稍后重试。'); } }

提示词工程技巧：

• 角色设定：开头明确AI的角色（“专业招聘顾问”），能引导其以更专业的视角进行分析。
• 结构化输出：要求以特定JSON格式输出，这是让AI返回可编程数据的关键。格式定义得越清晰，结果越稳定。
• 提供证据：要求为matchedSkills提供evidence，这迫使AI进行“引用”，增加了分析的可信度和可解释性。
• 处理非JSON响应：AI有时会在JSON外加一层Markdown代码块标记，代码中的replace操作就是为了处理这种情况，增强鲁棒性。
• 错误处理：必须用try-catch包裹API调用，处理网络错误、API限额、或AI返回非标准格式的情况，给用户友好的错误提示。

4.3 服务端API端点创建

在Nuxt 3中，在server/api目录下创建文件会自动生成API路由。我们来创建处理扫描请求的端点。

// server/api/scan.post.ts import { defineEventHandler, readMultipartFormData } from 'h3'; import { extractTextFromPDF } from '~/utils/pdfParser'; import { analyzeResumeWithAI } from '~/utils/aiAnalyzer'; export default defineEventHandler(async (event) => { // 1. 检查请求方法 if (event.method !== 'POST') { throw createError({ statusCode: 405, statusMessage: 'Method Not Allowed' }); } // 2. 读取表单数据（包含文件和文本） const formData = await readMultipartFormData(event); if (!formData) { throw createError({ statusCode: 400, statusMessage: 'No form data provided' }); } let resumeFile: File | null = null; let jobDescription: string = ''; // 3. 解析表单字段 for (const part of formData) { if (part.name === 'resume' && part.filename) { // 构建一个类似浏览器的File对象，需要data是Blob或Buffer resumeFile = new File([part.data], part.filename, { type: part.type }); } else if (part.name === 'jobDescription') { jobDescription = part.data.toString('utf-8'); } } if (!resumeFile) { throw createError({ statusCode: 400, statusMessage: 'Resume PDF file is required' }); } if (!jobDescription.trim()) { throw createError({ statusCode: 400, statusMessage: 'Job description is required' }); } try { // 4. 执行核心流程 const resumeText = await extractTextFromPDF(resumeFile); const analysisResult = await analyzeResumeWithAI(resumeText, jobDescription); // 5. 返回分析结果 return { status: 'success', data: analysisResult }; } catch (error: any) { console.error('Scan processing error:', error); // 根据错误类型返回更具体的错误信息 throw createError({ statusCode: 500, statusMessage: 'Failed to process scan. ' + (error.message || 'Internal server error'), }); } });

关键点解析：

• 文件上传处理：我们使用readMultipartFormData来处理包含文件上传的multipart/form-data请求。这在处理用户上传的PDF时是标准做法。
• 错误处理层级化：对请求方法、必填字段、处理过程中的错误都进行了分层处理，并返回恰当的HTTP状态码和消息，便于前端调试和用户理解。
• 安全性与限制：在生产环境中，务必添加文件大小限制、类型校验（确保是PDF）、甚至病毒扫描。可以考虑使用busboy或formidable进行更底层的流式处理，防止大文件耗尽服务器内存。

4.4 前端页面与组件集成

前端需要提供简历上传、JD输入、触发扫描和展示报告的功能。我们使用Nuxt UI组件来快速搭建。

<!-- pages/index.vue --> <template> <UContainer class="py-10"> <UCard> <template #header> <div class="flex items-center justify-between"> <h1 class="text-2xl font-bold">ATS 智能简历扫描器</h1> <UButton color="primary" :loading="isScanning" @click="runScan" :disabled="!canScan"> 开始扫描 </UButton> </div> </template> <div class="grid grid-cols-1 lg:grid-cols-2 gap-6"> <!-- 左侧：输入区 --> <div class="space-y-6"> <!-- 简历上传 --> <UFormGroup label="上传简历 (PDF)" required> <UInput type="file" accept=".pdf" @change="onFileChange" /> <p v-if="resumeFile" class="text-sm text-gray-500 mt-1"> 已选择: {{ resumeFile.name }} </p> </UFormGroup> <!-- 职位描述输入 --> <UFormGroup label="职位描述" required> <UTextarea v-model="jobDescription" placeholder="粘贴完整的职位描述文本..." :rows="10" autoresize /> </UFormGroup> </div> <!-- 右侧：结果展示区 --> <div class="space-y-6"> <div v-if="isScanning" class="flex flex-col items-center justify-center h-64"> <UIcon name="i-heroicons-arrow-path-20-solid" class="w-12 h-12 animate-spin text-primary" /> <p class="mt-4">AI正在分析您的简历，请稍候...</p> </div> <div v-else-if="scanResult"> <!-- 总体分数 --> <UCard> <template #header> <h2 class="text-xl font-semibold">匹配度报告</h2> </template> <div class="text-center"> <div class="inline-flex items-center justify-center"> <span class="text-5xl font-bold" :class="scoreColor">{{ scanResult.overallScore }}</span> <span class="text-2xl ml-2">/ 100</span> </div> <p class="text-gray-600 mt-2">{{ scanResult.summary }}</p> </div> </UCard> <!-- 匹配技能 --> <UCard> <template #header> <h3 class="text-lg font-semibold">匹配的技能</h3> </template> <div class="space-y-3"> <div v-for="(skill, index) in scanResult.matchedSkills" :key="index" class="border-l-4 pl-4" :class="relevanceBorderColor(skill.relevance)"> <p class="font-medium">{{ skill.skill }}</p> <p class="text-sm text-gray-600">“{{ skill.evidence }}”</p> <UBadge :color="relevanceBadgeColor(skill.relevance)" variant="soft" class="mt-1"> {{ skill.relevance }} 相关度 </UBadge> </div> </div> </UCard> <!-- 缺失技能与建议 --> <UCard v-if="scanResult.missingSkills.length > 0"> <template #header> <h3 class="text-lg font-semibold text-red-600">缺失的关键技能</h3> </template> <ul class="list-disc pl-5 space-y-1"> <li v-for="(skill, index) in scanResult.missingSkills" :key="index">{{ skill }}</li> </ul> </UCard> <!-- 优化建议 --> <UCard v-if="scanResult.suggestions.length > 0"> <template #header> <h3 class="text-lg font-semibold">优化建议</h3> </template> <ul class="space-y-2"> <li v-for="(suggestion, index) in scanResult.suggestions" :key="index" class="flex items-start"> <UIcon name="i-heroicons-light-bulb-20-solid" class="w-5 h-5 text-yellow-500 mr-2 mt-0.5 flex-shrink-0" /> <span>{{ suggestion }}</span> </li> </ul> </UCard> </div> <div v-else class="text-center text-gray-500 py-10"> <UIcon name="i-heroicons-document-magnifying-glass-20-solid" class="w-16 h-16 mx-auto opacity-50" /> <p class="mt-4">上传简历并输入职位描述，点击“开始扫描”获取智能分析报告。</p> </div> </div> </div> <!-- 错误提示 --> <UAlert v-if="errorMessage" icon="i-heroicons-exclamation-triangle-20-solid" color="red" variant="solid" :title="errorMessage" class="mt-6" /> </UCard> </UContainer> </template> <script setup lang="ts"> import type { ATSAnalysisResult } from '~/utils/aiAnalyzer'; const resumeFile = ref<File | null>(null); const jobDescription = ref(''); const isScanning = ref(false); const scanResult = ref<ATSAnalysisResult | null>(null); const errorMessage = ref(''); const canScan = computed(() => { return resumeFile.value && jobDescription.value.trim().length > 0; }); const scoreColor = computed(() => { if (!scanResult.value) return ''; const score = scanResult.value.overallScore; if (score >= 80) return 'text-green-600'; if (score >= 60) return 'text-yellow-600'; return 'text-red-600'; }); function relevanceBorderColor(relevance: string) { switch (relevance) { case 'high': return 'border-green-500'; case 'medium': return 'border-yellow-500'; case 'low': return 'border-gray-300'; default: return 'border-gray-300'; } } function relevanceBadgeColor(relevance: string) { switch (relevance) { case 'high': return 'green'; case 'medium': return 'yellow'; case 'low': return 'gray'; default: return 'gray'; } } function onFileChange(event: Event) { const target = event.target as HTMLInputElement; if (target.files && target.files[0]) { resumeFile.value = target.files[0]; } else { resumeFile.value = null; } // 清除旧结果 scanResult.value = null; errorMessage.value = ''; } async function runScan() { if (!canScan.value) return; isScanning.value = true; errorMessage.value = ''; scanResult.value = null; const formData = new FormData(); formData.append('resume', resumeFile.value!); formData.append('jobDescription', jobDescription.value); try { const { data, error } = await useFetch('/api/scan', { method: 'POST', body: formData, // 不将FormData自动转换为JSON headers: { Accept: 'application/json' }, }); if (error.value) { throw new Error(error.value.message || '扫描请求失败'); } if (data.value && data.value.status === 'success') { scanResult.value = data.value.data; } else { throw new Error('服务器返回了未知格式的数据'); } } catch (err: any) { console.error('扫描过程出错:', err); errorMessage.value = err.message || '分析过程中出现未知错误，请重试。'; } finally { isScanning.value = false; } } </script>

前端实现要点：

• 响应式设计：使用Tailwind的grid和响应式断点（lg:grid-cols-2）来创建左右分栏布局，在移动设备上自动堆叠。
• 状态管理：使用Vue的ref和computed来管理文件、文本、加载状态、结果和错误信息，逻辑清晰。
• 用户体验：提供了加载状态指示器、结果可视化（分数颜色、相关度徽章）、清晰的空状态和错误提示。
• 文件上传：使用原生<input type="file">结合FormData进行文件上传，这是与后端multipart/form-data端点配合的标准方式。
• API调用：使用Nuxt提供的useFetch组合式函数，它提供了更好的类型推断和错误处理集成。

5. 部署与生产环境优化

5.1 一键部署到Vercel

项目模板本身就支持Vercel部署。最简单的方式是：

1. 将你的代码推送到GitHub、GitLab或Bitbucket仓库。
2. 登录 Vercel ，点击“Add New...” -> “Project”。
3. 导入你的仓库。
4. Vercel会自动检测到这是Nuxt项目，并应用正确的构建配置。你只需要在环境变量设置中，添加你在.env文件中定义的NUXT_GEMINI_API_KEY。
5. 点击“Deploy”。部署完成后，你会获得一个永久的访问链接。

部署配置要点（vercel.json）：虽然Vercel通常能自动配置，但为了更精确的控制，可以在项目根目录创建vercel.json：

{ "builds": [ { "src": "nuxt.config.ts", "use": "@vercel/nuxt" } ], "routes": [ { "handle": "filesystem" }, { "src": "/(.*)", "dest": "/" } ] }

5.2 生产环境关键优化

1. API密钥安全：确保NUXT_GEMINI_API_KEY只在Vercel的项目环境变量中设置，绝不提交到代码库。可以考虑使用Vercel的环境变量加密功能。

2. 文件上传限制：在server/api/scan.post.ts中，添加文件大小和类型校验。

   // 在解析formData后添加 const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB if (resumeFile.size > MAX_FILE_SIZE) { throw createError({ statusCode: 413, statusMessage: 'Resume file size exceeds 5MB limit.' }); } if (resumeFile.type !== 'application/pdf') { throw createError({ statusCode: 415, statusMessage: 'Only PDF files are allowed.' }); }

3. AI API调用限流与缓存：为了防止滥用和控制成本，应该对扫描接口进行限流。可以使用Nuxt Server Middleware或第三方服务（如Upstash）来实现简单的速率限制。对于相同的简历和JD组合，可以考虑缓存分析结果一段时间（例如24小时），避免重复调用AI API产生不必要的费用。

4. 错误监控与日志：集成像Sentry这样的错误监控工具，捕获运行时错误。在Vercel上，可以方便地查看函数日志。

5. 性能优化：PDF解析和AI调用都是耗时操作。确保Vercel的函数超时时间设置得足够长（默认10秒，对于复杂简历可能不够）。可以考虑：

   • 前端优化：使用异步上传，并提供进度提示。
   • 后端优化：如果解析时间非常长，可以考虑引入任务队列（如BullMQ），将扫描任务放入队列异步处理，并通过WebSocket或轮询通知前端结果。但这会大大增加架构复杂度。

6. 常见问题与排查技巧实录

在实际开发和测试中，你可能会遇到以下问题：

问题1：PDF解析后文本乱码或为空。

• 排查：首先确认PDF是文本型而非扫描件。可以用Adobe Acrobat或预览程序打开，尝试选择文字。如果可选，则是文本型。
• 解决：对于文本型PDF仍解析失败，可能是字体编码问题。尝试在extractTextFromPDF函数中，使用pdf.getTextContent()返回的items时，检查每个item的transform矩阵和fontName属性，有时需要更复杂的文本重组逻辑。对于扫描件，必须集成OCR，可以调研tesseract.js，但要注意这会显著增加客户端包体积和处理时间。

问题2：AI返回的格式不符合JSON，导致JSON.parse失败。

• 排查：打印出AI返回的原始text，看它是否包含了额外的说明、Markdown格式错误或JSON格式错误。
• 解决：
  1. 强化提示词：在Prompt中更严厉地强调“只输出JSON，不要有任何其他文字”。
  2. 更健壮的解析：使用更宽容的解析方式，例如寻找第一个{和最后一个}之间的内容。

  const jsonMatch = text.match(/\{[\s\S]*\}/); if (jsonMatch) { try { return JSON.parse(jsonMatch[0]); } catch (e) { // 处理解析错误 } }

  3. 降级处理：如果JSON解析失败，尝试让AI重新生成，或者返回一个包含错误信息的友好响应给用户。

问题3：部署到Vercel后，API路由返回404或500错误。

• 排查：
  • 检查Vercel控制台部署日志，看构建是否成功。
  • 检查函数日志，看运行时是否有错误（如缺少环境变量）。
  • 本地使用bun build和bun preview模拟生产环境，看问题是否能复现。
• 解决：
  • 环境变量：确保在Vercel项目设置中正确配置了NUXT_GEMINI_API_KEY，且名称与代码中读取的（NUXT_GEMINI_API_KEY）一致。
  • 路径问题：确保API路由文件位于正确的server/api目录下，且文件名正确（scan.post.ts对应/api/scan的POST请求）。
  • 依赖问题：确保package.json中的依赖都是最新且兼容的。特别是pdfjs-dist，在服务端和客户端环境下的行为可能有差异。

问题4：处理大PDF文件时，服务器函数超时。

• 现象：Vercel Serverless函数默认超时时间为10秒（Hobby计划）或15秒（Pro计划）。解析一个复杂、多页的PDF并等待AI响应可能超过此限制。
• 解决：
  • 优化解析：只解析前几页（例如前5页）的简历内容，通常关键信息都在前面。
  • 分步处理：改为异步任务流程。前端上传后，后端立即返回一个任务ID，然后在后台Worker中处理，处理完成后将结果存储到数据库或缓存，前端通过轮询或WebSocket获取结果。这需要引入更复杂的基础设施（如队列、数据库）。
  • 升级计划：考虑升级到Vercel Pro计划以获得更长的超时时间（60秒），但这只是缓解，不是根本解决。

问题5：AI分析结果不够准确或泛泛而谈。

• 解决：这属于提示词优化范畴。
  • 提供示例：在Prompt中提供一两个输入输出的示例（Few-shot Learning），能显著提升AI遵循格式和理解任务的能力。
  • 更具体的指令：将“分析匹配度”拆解成更具体的子任务，例如：“首先，从JD中提取出5个最关键的核心技能和要求。然后，逐条在简历中寻找对应证据...”。
  • 调整模型和参数：尝试不同的模型（如从gemini-1.5-flash切换到gemini-1.5-pro以获得更好推理能力）或调整生成参数（如temperature调低以获得更确定性输出）。
  • 后处理：对AI返回的结果进行后处理，比如过滤掉置信度过低的匹配项，或者对分数进行标准化校准。

这个ats-scanner项目从一个简单的模板开始，通过集成PDF解析和AI能力，变成了一个实用的生产力工具。它的价值不在于技术栈有多新颖，而在于用恰当的技术组合解决了一个具体的痛点。开发过程中，最大的挑战往往不是代码本身，而是对边界情况的处理（如奇葩的PDF格式）、对AI输出的驯服，以及对用户体验细节的打磨。希望这份详细的拆解能为你实现类似想法提供一个坚实的起点。记住，从核心功能闭环开始，再逐步迭代优化，是构建此类工具的最佳路径。