Vite React应用部署问题：npm run build执行失败

1. 修复npm run build报错“../assets is outside src/” #

尽管assets目录确实在src内，但路径解析错误通常是引用写法或Vite配置导致的，按以下步骤排查：

• 统一资源引用路径：src内组件/样式文件引用assets时，使用相对路径（比如组件在src/components/Header.jsx，引用src/assets/logo.png写../assets/logo.png；根目录文件如App.jsx直接写./assets/logo.png）；如果嫌相对路径麻烦，推荐配置src别名，避免路径混乱：
  在vite.config.js/vite.config.ts中添加：

  import { defineConfig } from 'vite';
  import react from '@vitejs/plugin-react';
  import path from 'path';
  
  export default defineConfig({
    plugins: [react()],
    resolve: {
      alias: {
        '@': path.resolve(__dirname, './src'),
      },
    },
  });
  

  之后可以用@/assets/logo.png直接引用资源，无需关心文件层级。
• 清理Vite缓存：删除node_modules/.vite目录（Mac/Linux用rm -rf node_modules/.vite，Windows用rd /s /q node_modules\.vite），再重新执行npm run build。

2. 解决部署后链接无法访问的问题 #

这大概率是GitHub Pages的路径特性和前端路由不匹配导致的，按以下操作修复：

• 配置Vite的base路径：在vite.config.js中添加base参数，值为你的仓库名称（比如仓库叫my-react-app，则写base: '/my-react-app/'），示例：

  export default defineConfig({
    plugins: [react()],
    base: '/my-react-app/',
    // 其他已配置内容...
  });
  

• 适配前端路由：如果使用react-router-dom，将BrowserRouter替换为HashRouter，因为GitHub Pages不支持前端路由的刷新跳转，HashRouter通过URL哈希值处理路由，避免404：

  // 替换前
  // import { BrowserRouter } from 'react-router-dom';
  // 替换后
  import { HashRouter } from 'react-router-dom';
  
  ReactDOM.createRoot(document.getElementById('root')).render(
    <HashRouter>
      <App />
    </HashRouter>
  );
  

• 检查GitHub Pages部署设置：进入仓库Settings -> Pages，确认Source选择的是正确的部署方式：
  • 若用分支部署，选择gh-pages分支，目录选/root；
  • 若用GitHub Actions，确保Workflow配置正确打包dist目录并部署。
• 简化部署流程：安装gh-pages工具（npm install gh-pages --save-dev），在package.json中添加部署脚本：

  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  }
  

  之后执行npm run deploy即可自动打包并将dist内容推送到gh-pages分支完成部署。

内容的提问来源于stack exchange，提问作者Pratikshit Kumar