Capacitor 打包后为什么无法访问本地 HTML 文件？

含平的笔记提问于 2026-02-26 20:57:27 阅读 12

移动

我用 Capacitor 把一个纯静态的 Vue 项目打包成 Android 应用，开发时在浏览器里一切正常，但打包安装到手机后白屏。看 Logcat 发现报错说找不到 index.html，可明明文件就在 www 目录下啊。

我试过手动把 dist 文件复制到 android/app/src/main/assets/public，也试过重新运行 npx cap sync，但还是不行。是不是路径配置有问题？

我的 capacitor.config.ts 是这样写的：

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'MyApp',
  webDir: 'dist',
  bundledWebRuntime: false
};

export default config;

我来解答赞 7 收藏

反馈

1 条解答

令狐长永 Lv1

第一步，先确认你打包后的文件结构对不对。Capacitor 在打包 Android 应用时，会把 webDir 指定的目录内容复制到 android/app/src/main/assets/public 目录下，但这个复制行为只有在你执行了 npx cap sync 或 npx cap build android 后才会发生。

你提到试过手动复制 dist 到 assets/public，但这里有个坑：Capacitor 实际上会把整个 webDir 的内容复制到 assets/public/ 下，而不是把 dist 里的内容直接放在 assets/public 根目录。也就是说，如果你的 webDir 是 'dist'，那么最终在手机里，文件应该在 assets/public/dist/index.html 这个路径，而不是 assets/public/index.html。

第二步，检查 AndroidManifest.xml 和 WebView 配置有没有问题。Capacitor 默认会从 file:///android_asset/public/dist/index.html 加载你的页面，这个路径是 Capacitor 内部硬编码的逻辑，除非你改了 server.url 配置。但你这个配置里没配 server，所以它会走默认路径。

第三步，重点排查：你打包出来的 dist 目录里，到底有没有 index.html？有没有可能你用的是 Vue 的 history 模式？如果是的话，本地开发没问题，但打包成 Android 原生应用时，没有 HTTP 服务器做路径重定向，直接打开文件路径就会 404。Vue 的 history 模式需要服务器配置 fallback 到 index.html，而本地文件系统没有这个能力。

建议你先改用 hash 模式试试看。在 vue.config.js 里加一行：

module.exports = {

  publicPath: './',

  configureWebpack: {

    output: {

      publicPath: './'

    }

  },

  lintOnSave: false,

  devServer: {

    historyApiFallback: true

  }

}

注意 publicPath: './' 这个配置特别关键，它会让所有静态资源路径变成相对路径，而不是默认的绝对路径（比如 /js/app.js），否则在 file:// 协议下会找不到资源。

第四步，重新打包一遍，别跳步骤：

1. 先执行 npm run build，确保 dist 目录生成成功
2. 检查 dist 目录里确实有 index.html 和 JS/CSS 文件
3. 然后执行 npx cap sync，让 Capacitor 把 dist 整个复制到 android/app/src/main/assets/public 下
4. 再执行 npx cap open android 打开 Android Studio
5. 点击 Build > Clean Project，再 Build > Rebuild Project
6. 最后 Run 到手机

如果还是白屏，打开 Logcat，重点看有没有类似 File not found 或 net::ERR_FILE_NOT_FOUND 的错误。如果看到 file:///android_asset/public/dist/index.html 找不到，说明你 dist 根本没被正确复制进去；如果看到 JS 文件 404，大概率是 publicPath 配置问题。

我之前踩过一个坑：Vue 项目用了 vite-plugin-pwa，它会生成 sw.js，但 Capacitor 默认不包含 service worker，导致页面加载后缓存策略失败，也会白屏。如果你用了 PWA 相关插件，记得在 capacitor.config.ts 里加一句：

const config: CapacitorConfig = {

  appId: 'com.example.myapp',

  appName: 'MyApp',

  webDir: 'dist',

  bundledWebRuntime: false,

  android: {

    webContentsDebuggingEnabled: true // 开启调试，方便看 Logcat

  }

};

最后提醒一句：别在本地手动改 android/app/src/main/assets 里的文件，Capacitor 每次 sync 都会覆盖它，你改了也白改。所有 web 资源必须通过 webDir + sync 的方式来更新。

如果按上面步骤还解决不了，把你的 dist 目录结构贴出来，我帮你看看是不是漏了什么文件。

2026-02-26 21:01