From 61a58554a67f03206bb1cde294111040b9822452 Mon Sep 17 00:00:00 2001
From: Haoqun Jiang <haoqunjiang@gmail.com>
Date: Fri, 22 Feb 2019 22:16:41 +0800
Subject: [PATCH] docs: add a troubleshooting page for common issues (#3479)

---
 docs/.vuepress/config.js      |  3 ++-
 docs/guide/troubleshooting.md | 31 +++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)
 create mode 100644 docs/guide/troubleshooting.md

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index e9d11c907..dbaeb743a 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -103,7 +103,8 @@ module.exports = {
                 '/guide/webpack',
                 '/guide/mode-and-env',
                 '/guide/build-targets',
-                '/guide/deployment'
+                '/guide/deployment',
+                '/guide/troubleshooting'
               ]
             }
           ],
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
new file mode 100644
index 000000000..d5d6683c8
--- /dev/null
+++ b/docs/guide/troubleshooting.md
@@ -0,0 +1,31 @@
+# Troubleshooting
+
+## Running installation with `sudo` or as `root`
+
+If you install `@vue/cli-service` as `root` user or with `sudo`, there might be issues when running package `postinstall` scripts.
+
+This is a security feature of npm. You should always avoid running npm with root privileges because install scripts can be unintentionally malicious.
+
+If you must however, you can workaround this error by setting the `--unsafe-perm` flag of npm. This can be done by prefixing the command with an environment variable, i.e.
+
+```bash
+npm_config_unsafe_perm=true vue create my-project
+```
+
+## Symbolic Links in `node_modules`
+
+If there're dependencies installed by `npm link` or `yarn link`, ESLint (and sometimes Babel as well) may not work properly for those symlinked dependencies. It is because [webpack resolves symlinks to their real locations by default](https://webpack.js.org/configuration/resolve/#resolvesymlinks), thus breaks ESLint / Babel config lookup.
+
+A workaround for this issue is to manually disable symlinks resolution in webpack:
+
+```js
+// vue.config.js
+module.exports = {
+  chainWebpack: (config) => {
+    config.resolve.symlinks(false)
+  }
+}
+```
+
+::: warning
+Disabling `resovle.symlinks` may break hot module reloading if your dependencies are installed by third-party npm clients that utilized symbolic links, such as`cnpm` or `pnpm`.