Frequently Asked Questions #

Listed are some common questions

If you have a question, you can first look here. If not found, you can search or submit your question on GitHub Issue, or if it's a discussion-type question, you can go to GitHub Discussions

Instructions

If you encounter a problem, you can start looking from the following aspects:

1. Search the corresponding module's GitHub repository issue
2. Search for the problem on Google
3. Search for the problem on Baidu
4. If you can't find the issue in the list below, you can ask in issues
5. If it's not a problem type and needs discussion, please go to discussions to discuss

Dependency Issues

In a Monorepo project, it is necessary to develop the habit of executing pnpm install every time you git pull the code, as new dependency packages are often added. The project has already configured automatic execution of pnpm install in .husky/git-merge, but sometimes there might be issues. If it does not execute automatically, it is recommended to execute it manually once.

About Cache Update Issues

The project configuration is by default cached in localStorage, so some configurations may not change after a version update.

The solution is to modify the version number in package.json each time the code is updated. This is because the key for localStorage is based on the version number. Therefore, after an update, the configurations from a previous version will become invalid. Simply re-login to apply the new settings.

About Modifying Configuration Files

When modifying environment files such as .env or the vite.config.ts file, Vite will automatically restart the service.

There's a chance that automatic restarts may encounter issues. Simply rerunning the project can resolve these problems.

Errors When Running Locally

Since Vite does not transform code locally and the code uses relatively new syntax such as optional chaining, local development requires using a higher version of the browser (Chrome 90+).

Blank Page After Switching Pages

This issue occurs because route switching animations are enabled, and the corresponding page component has multiple root nodes. Adding a <div></div> at the outermost layer of the page can solve this problem.

Incorrect Example

<template>
  <!-- Annotations are also considered a node -->
  <h1>text h1</h1>
  <h2>text h2</h2>
</template>

正确示例

<template>
  <div>
    <h1>text h1</h1>
    <h2>text h2</h2>
  </div>
</template>

Tip

• If you want to use multiple root tags, you can disable route switching animations.
• Root comment nodes under template are also counted as a node.

My code works locally but not when packaged

The reason for this issue could be one of the following. You can check these reasons, and if there are other possibilities, feel free to add them:

• The variable ctx was used, which is not exposed in the instance type. The Vue official documentation also advises against using this property as it is intended for internal use only.

import { getCurrentInstance } from 'vue';
getCurrentInstance().ctx.xxxx;

Dependency Installation Issues

• If you cannot install dependencies or the startup reports an error, you can try executing pnpm run reinstall.
• If you cannot install dependencies or encounter errors, you can try switching to a mobile hotspot for installing dependencies.
• If that still doesn't work, you can configure a domestic mirror for installation.
• You can also create a .npmrc file in the project root directory with the following content:

# .npmrc
registry = https://registry.npmmirror.com/

Package File Too Large

• First, the full version will be larger because it includes many library files. You can use the simplified version for development.

• Secondly, it is recommended to enable gzip, which can reduce the size to about 1/3 of the original. Gzip can be enabled directly by the server. If so, the frontend does not need to build .gz format files. If the frontend has built .gz files, for example, with nginx, you need to enable the gzip_static: on option.

• While enabling gzip, you can also enable brotli for better compression than gzip. Both can coexist.

Note

• gzip_static: This module requires additional installation in nginx, as the default nginx does not include this module.

• Enabling brotli also requires additional nginx module installation.

Runtime Errors

If you encounter errors similar to the following, please check that the full project path (including all parent paths) does not contain Chinese, Japanese, or Korean characters. Otherwise, you will encounter a 404 error for the path, leading to the following issue:

[vite] Failed to resolve module import "ant-design-vue/dist/antd.css-vben-adminode_modulesant-design-vuedistantd.css". (imported by /@/setup/ant-design-vue/index.ts)

Console Route Warning Issue

If you see the following warning in the console, and the page can open normally, you can ignore this warning.

Future versions of vue-router may provide an option to disable this warning.

[Vue Router warn]: No match found for location with path "xxxx"

Startup Error

If you encounter the following error message, please check if your nodejs version meets the requirements.

TypeError: str.matchAll is not a function
at Object.extractor (vue-vben-admin-main\node_modules@purge-icons\core\dist\index.js:146:27)
at Extract (vue-vben-admin-main\node_modules@purge-icons\core\dist\index.js:173:54)

nginx Deployment

After deploying to nginx，you might encounter the following error:

Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "application/octet-stream". Strict MIME type checking is enforced for module scripts per HTML spec.

Solution:

http {
    types {
      application/javascript js mjs;
    }
}

Contributors

invalid w

Li Kui

Changelog

Last edited 28 days ago

View full history

8230493-feat(@vben/docs): support english documents (#4202)