AniShort本地无法打开页面的根本原因是启动链路基础环节错配：Node/npm版本不匹配、依赖未正确安装或误用file://协议访问。需依次验证package.json完整性、node_modules存在性、Node≥18.17.0版本、npm install彻底性及vite.config.ts的base配置，并确保通过http://localhost:5173访问而非双击index.html。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
协作者在本地克隆 AniShort 项目后双击 index.html 或运行 npm run dev 却打不开页面，浏览器显示空白、404、跨域错误或控制台报错“Failed to load module”，说明项目未进入可交互状态。这通常不是代码逻辑问题，而是启动链路中某个基础环节缺失或错配。
先确认项目是否真的能被识别为 AniShort
打开终端，进入项目根目录，执行 cat package.json | grep -i \"ani\"。如果返回空，或只显示 "name": "ani-short" 但无 "scripts": {"dev": ...} 字段，说明你拿到的不是完整源码包——可能是 GitHub 页面导出的静态 ZIP、误下载了文档分支、或被 CI 构建产物覆盖了源码。此时应重新从主分支 clone，且确保 URL 含 【/tree/main】 或明确指向源码根目录。
检查 node_modules 是否存在且非空：ls -la node_modules | head -n 5。若该目录不存在、为空、或只有 .bin 子目录，说明依赖根本没装成功，后续所有操作都无效。
检查 Node 和 npm 版本是否匹配项目要求
执行 node --version && npm --version。AniShort 是基于 Vue 3 + Vite 构建的轻量动画工具链，要求 Node ≥ 18.17.0，npm ≥ 9.6.0。若显示 v16.20.2 或 v20.12.0，必须切换版本——v16 太旧会触发 vite 依赖解析失败，v20.12+ 则因 OpenSSL 3.0 兼容性问题导致 crypto 模块报 digital envelope routines 错误。
方法一：用 nvm 切换（推荐）
运行 nvm list 查看已安装版本 → 若无 18.17.2，执行 nvm install 18.17.2 → 再执行 nvm use 18.17.2。
方法二：手动降级（仅 Windows 临时应急）
去 Node.js 官网下载 18.17.2 LTS Windows Installer，勾选 “Automatically install the necessary tools” 并覆盖安装，重启终端生效。
【切勿跳过此步直接重装依赖——版本不匹配时，npm install 会静默生成损坏的 node_modules】
验证依赖是否真正安装完整
第一步：删干净残留
执行 rm -rf node_modules package-lock.json（macOS/Linux）或 rd /s /q node_modules & del package-lock.json（Windows CMD）。注意不要只删 node_modules 而留着 lock 文件，否则 npm install 会按旧锁文件恢复不兼容版本。
第二步：换源并重装
国内协作者务必先执行 npm config set registry https://registry.npmmirror.com，再运行 npm install。若卡在 node-sass 或 sharp 下载，说明镜像未生效，立即中断并改用 npm install --no-fund --legacy-peer-deps 强制跳过资金提示与 peer 依赖校验。
第三步：验证关键模块是否存在
安装完成后，执行 ls node_modules/vite 和 ls node_modules/@vue/compiler-sfc。两个路径都必须存在且含 dist/ 目录。若 vite 缺失，说明 scripts 中的 dev 命令根本找不到执行入口，npm run dev 必然报错 “command not found”。
排查本地服务启动后的访问路径
运行 npm run dev，观察终端输出。正常应出现类似 “Local: http://localhost:5173/” 的地址行，并停在监听状态。若输出后立即退出，或卡在 “vite:dep-scan” 不动，说明插件加载失败，需检查 vite.config.ts 中是否引用了本地未安装的插件（如 @anishde12020/vite-plugin-ffmpeg）。
浏览器必须访问 http://localhost:5173，不能访问 file:/// 路径下的 index.html——后者会因浏览器同源策略禁止加载 ./src/main.js 中的 import 语句，导致白屏且控制台报 CORS 错误。
若访问 localhost:5173 显示 404，检查 vite.config.ts 中 base 配置是否被误设为 "/ani-short/"。这种相对路径只适用于部署到子目录，开发时必须保持默认值 "" 或显式设为 "/"。
