Vite production build asset 404s when deploying to subpaths

Solving Asset Resolution Failures

To resolve 404 errors when deploying a Vite application to a subpath, you must align the base configuration in vite.config.js with your deployment directory. By default, Vite uses /, which generates absolute paths that fail when the app is hosted at a location like /my-app/.

Configuration Options

Depending on your deployment requirements, use one of the following settings:

• Absolute Subpath: Use base: '/my-app/' if the deployment path is static and known. This ensures all assets are prefixed with the specific subpath.
• Relative Paths: Use base: './' to make asset references relative to the index.html file. This allows the build to be portable across different subpaths without modification.

// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  base: '/my-app/', // or './' for relative paths
})

Technical Explanations

Relative vs. Absolute Resolution

Vite distinguishes between these paths during the Rollup bundling phase. An absolute base (/my-app/) hardcodes the prefix into the HTML and JS chunks. A relative base (./) instructs the browser to resolve assets relative to the current URL. While relative paths offer portability, they can cause 404s if you use client-side routing (e.g., React Router or Vue Router) with "pretty URLs" (like /my-app/user/profile), as the browser may attempt to find assets relative to the /user/ directory rather than the app root.

Consistency of BASE_URL

Because import.meta.env.BASE_URL is a static replacement performed at build time, it cannot be changed at runtime. To maintain consistency across varying environments without a full rebuild, the most reliable approach is to use relative paths (./). If absolute paths are required for routing stability, you must use environment variables during the build process to inject the correct base path for each specific target environment.

Verification Steps

1. Run your build command: npm run build.
2. Open the generated dist/index.html file.
3. Verify that <script> and <link> tags start with your specified subpath or ./ rather than a leading slash.

Diagnostic Note: Are you using a client-side router with history mode? If so, relative paths may fail on deep-linked pages, and a specific absolute subpath is required.