feat: 添加文章
添加 IDEA 因为中文路径导致 Git Clone 报错的文章与修改 Windows 用户名的文章
This commit is contained in:
5 files changed
+622
-1
No files matched your search
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: JetBrains IDE Prompting for the Git User's Password When Cloning over SSH
|
||||
tags:
|
||||
- jetbrains
|
||||
- git
|
||||
- ssh
|
||||
- windows
|
||||
author:
|
||||
name: Zihlu Wang
|
||||
email: real@zihluwang.me
|
||||
---
|
||||
|
||||
When you develop on Windows with a JetBrains IDE — IntelliJ IDEA, PyCharm, WebStorm, GoLand and friends — and your local Windows username contains non-ASCII characters such as Chinese, cloning a repository over SSH can behave rather oddly:
|
||||
|
||||
> The remote is configured as an SSH URL, yet you are repeatedly prompted for the Git user's password.
|
||||
|
||||
Take a repository address such as:
|
||||
|
||||
```text
|
||||
git@git.example.com:project/demo.git
|
||||
```
|
||||
|
||||
Normally Git authenticates over SSH with a key pair and should never ask for the Git user's own login password.
|
||||
|
||||
The problem may be invisible in command-line Git, but it can surface in a JetBrains IDE when you clone, pull or push.
|
||||
|
||||
## Symptoms
|
||||
|
||||
Suppose the Windows username is:
|
||||
|
||||
```text
|
||||
张三
|
||||
```
|
||||
|
||||
Its home directory will be:
|
||||
|
||||
```text
|
||||
C:\Users\张三
|
||||
```
|
||||
|
||||
In the IDE, choose:
|
||||
|
||||
```text
|
||||
Git → Clone → Repository URL
|
||||
```
|
||||
|
||||
and enter:
|
||||
|
||||
```text
|
||||
git@git.example.com:project/demo.git
|
||||
```
|
||||
|
||||
After you click Clone, you may see something like:
|
||||
|
||||
```text
|
||||
git@git.example.com's password:
|
||||
```
|
||||
|
||||
or the IDE may pop up a password dialog asking for the Git user's password. Even entering the correct password may fail to complete the clone.
|
||||
|
||||
## Why does an SSH URL ask for a password?
|
||||
|
||||
To make sense of this, you first need to understand how SSH falls back between authentication methods.
|
||||
|
||||
SSH tries authentication methods in order:
|
||||
|
||||
1. **Public key authentication** — the client presents a local private key, and the server checks whether the matching public key appears in `~/.ssh/authorized_keys` (on a Git server, among the SSH keys you have uploaded);
|
||||
2. **Password / keyboard-interactive authentication** — if public key authentication does not succeed, the server carries on and asks for a password.
|
||||
|
||||
So when `git@git.example.com's password:` appears in the IDE, **the problem is not that SSH was bypassed — it is that public key authentication failed**: the SSH client could not produce the right private key, so the server fell back to password authentication and is now asking for the password of the `git` account on the server — the `git` account, note, not your own. And because mainstream Git servers (GitLab, Gitea and the like) disable password login for `git` by default, supplying the correct password still gets you nowhere.
|
||||
|
||||
The root of the problem is that **the client cannot find the private key**.
|
||||
|
||||
On Windows with a Chinese username, this is usually down to path encoding. By default the private key lives at:
|
||||
|
||||
```text
|
||||
C:\Users\张三\.ssh\id_rsa
|
||||
```
|
||||
|
||||
The SSH client — whether it is the OpenSSH bundled with Git for Windows or the SSH implementation built into the JetBrains IDE — locates this directory through the `%USERPROFILE%` or `HOME` environment variable. When the username contains non-ASCII characters, that path is liable to be mangled as it crosses process boundaries (shuttled back and forth between UTF-8, GBK and ANSI), so the `~/.ssh` path the client resolves no longer matches the real one — neither `config` nor the private key can be read, and password authentication is all that is left.
|
||||
|
||||
A handy way to tell: **run `ssh -T git@git.example.com` in a terminal and it greets you normally, yet the IDE still demands a password when cloning.** That tells you the key itself is fine, and the fault lies purely in the IDE's path resolution.
|
||||
|
||||
## How to confirm
|
||||
|
||||
1. Check that the remote really is an SSH URL (`git@host:path` or `ssh://git@host/path`) and not an HTTP one.
|
||||
2. Run `ssh -T git@git.example.com` in a terminal:
|
||||
- Everything works → the key and the server configuration are fine, and the problem lies with the IDE;
|
||||
- It fails too → work through the usual suspects first: the private key file, `~/.ssh/config`, and whether the public key has been uploaded to the server.
|
||||
3. In the IDE, check which SSH implementation Git is using: `Settings → Version Control → Git → SSH executable`.
|
||||
4. Check that `C:\Users\张三\.ssh` really exists, and that whatever is in `config` is being read.
|
||||
|
||||
## Temporary workarounds
|
||||
|
||||
Before you rearrange your username, try one of the following to sidestep the non-ASCII path.
|
||||
|
||||
### Option 1: use the ssh.exe bundled with Git
|
||||
|
||||
A JetBrains IDE may default to its own built-in SSH implementation. Change `Settings → Version Control → Git → SSH executable` to `Native`, which makes it use the `ssh.exe` shipped with Git for Windows, then retry the clone. The two implementations resolve paths differently, and switching is often enough to sidestep the issue entirely.
|
||||
|
||||
### Option 2: move the keys to a pure-ASCII path and point at them explicitly
|
||||
|
||||
Copy the key directory from `C:\Users\张三\.ssh` to `C:\ssh`, then tell Git explicitly which private key and known_hosts file to use:
|
||||
|
||||
```shell
|
||||
git config --global core.sshCommand "ssh -i C:/ssh/id_rsa -o UserKnownHostsFile=C:/ssh/known_hosts"
|
||||
```
|
||||
|
||||
Once configured, command-line Git — and any IDE that shells out to the system Git — will use this command, and nothing depends on guessing `~/.ssh` any more.
|
||||
|
||||
### Option 3: give the IDE its own HOME
|
||||
|
||||
Create a pure-ASCII home directory (say `C:\ssh-home`), place your keys in `C:\ssh-home\.ssh\`, and set the following in the environment the IDE runs with:
|
||||
|
||||
```text
|
||||
HOME=C:\ssh-home
|
||||
```
|
||||
|
||||
SSH will then look for its configuration and private keys under `C:\ssh-home\.ssh\`, avoiding the Chinese path altogether.
|
||||
|
||||
> All three options relieve the symptom, but they are patches, not cures. As long as the username remains Chinese, other tools — Node, Python, Docker and any number of CLI utilities — can still trip over exactly the same problem. **The proper fix is to change the Windows username to English**, and the steps are in [Renaming a Windows User Account and Profile Folder to English](./rename-windows-user-profile-to-english.mdx).
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
title: Renaming a Windows User Account and Profile Folder to English
|
||||
tags:
|
||||
- windows
|
||||
- user-profile
|
||||
- registry
|
||||
- troubleshooting
|
||||
author:
|
||||
name: Zihlu Wang
|
||||
email: real@zihluwang.me
|
||||
---
|
||||
|
||||
import { Kbd } from "@rspress/core/theme"
|
||||
|
||||
Windows works perfectly well with a Chinese username, but it makes life needlessly difficult for a good many developer tools — the most glaring example being [a JetBrains IDE that keeps asking for a password when cloning over SSH](./jetbrains-git-ssh-clone-password-prompt.md). The culprit is the non-ASCII characters in `C:\Users\张三`: Git, Node, Python, Docker and a host of CLI tools each read that path with their own idea of the correct encoding, and sooner or later one of them gets it wrong.
|
||||
|
||||
Renaming the account to English sorts this whole class of problem out in one go. The procedure is not complicated, but it is sensitive to the **order of the steps** and to **when you restart**, so follow along below.
|
||||
|
||||
:::warning Before you start
|
||||
|
||||
This procedure edits the **registry** and renames a **user profile folder**, so it carries real risk. Before you begin:
|
||||
|
||||
- Back up important data (the desktop, your documents, and the configuration directories of any applications you rely on);
|
||||
- Make sure the account you are using has **administrator** rights;
|
||||
- Create a system restore point first, so that you can roll back if something goes wrong midway;
|
||||
- Follow the steps below in order — do not skip any, and pay particular attention to the timing of the restarts.
|
||||
|
||||
:::
|
||||
|
||||
## The general idea
|
||||
|
||||
The word "username" on Windows actually covers two separate things:
|
||||
|
||||
1. **The account's display name** — the name shown on the sign-in screen and in the Start menu;
|
||||
2. **The user profile folder name** — the `C:\Users\<name>` folder.
|
||||
|
||||
The awkward part is that Windows will not let you rename the profile folder of a user who is signed in; and since the registry records the **absolute path** of that folder, renaming the folder without touching the registry means your profile cannot be mounted the next time you sign in.
|
||||
|
||||
So a "go-between" account is needed to do the work:
|
||||
|
||||
> Create a temporary account → sign in as it → rename the folder → edit the registry → return to your own account.
|
||||
|
||||
## 1. Find the SID of the existing account
|
||||
|
||||
Sign in as your current account (the one with the Chinese name) and open PowerShell or Command Prompt:
|
||||
|
||||
```powershell
|
||||
whoami /user
|
||||
```
|
||||
|
||||
The output looks like this:
|
||||
|
||||
```text
|
||||
User information
|
||||
----------------
|
||||
User Name SID
|
||||
================= ============================================
|
||||
desktop-abc\张三 S-1-5-21-1234567890-1234567890-1234567890-1001
|
||||
```
|
||||
|
||||
Note the string at the end, `S-1-5-21-...-1001`. That is the `{old user SID}` you will need later.
|
||||
|
||||
To list every local account and its SID in one go:
|
||||
|
||||
```powershell
|
||||
wmic useraccount get name,sid
|
||||
|
||||
# or, on more recent versions of PowerShell:
|
||||
Get-LocalUser | Select-Object Name, SID
|
||||
```
|
||||
|
||||
## 2. Create a new local Windows account
|
||||
|
||||
Open `Settings → Accounts → Other users → Add account`. When asked how the person will sign in, choose **"I don't have this person's sign-in information"**, then **"Add a user without a Microsoft account"**, and create a local account with a plain English name such as `tempadmin`.
|
||||
|
||||
When it has been created, select it in the Other users list, choose **Change account type**, and make it an **administrator**.
|
||||
|
||||
This account is purely a go-between. Its purpose is to let you work on your own profile's files and registry entries **while your own account is signed out**.
|
||||
|
||||
## 3. Sign out of your account and sign in as the new one
|
||||
|
||||
Save your work, sign out of your current account, restart the computer, and sign in with the temporary account you have just created.
|
||||
|
||||
## 4. Rename the profile folder
|
||||
|
||||
Still signed in as the temporary account, open **File Explorer**, go to `C:\Users`, and rename `张三` to the English name you want (for example `JohnDoe`):
|
||||
|
||||
```text
|
||||
C:\Users\张三 → C:\Users\JohnDoe
|
||||
```
|
||||
|
||||
If Windows complains that the folder is in use, some process belonging to your original account is still running (a background service, a sync client, a resident utility). A full restart usually clears it; alternatively, rename it from the command line:
|
||||
|
||||
```powershell
|
||||
Rename-Item -Path "C:\Users\张三" -NewName "JohnDoe"
|
||||
```
|
||||
|
||||
:::tip Naming advice
|
||||
Stick to letters and digits, and avoid spaces. `C:\Users\zhang san` does work, but the space will cause trouble with some command-line tools all the same.
|
||||
:::
|
||||
|
||||
## 5. Update ProfileImagePath in the registry
|
||||
|
||||
Press <Kbd>Win</Kbd> + <Kbd>R</Kbd>, type `regedit` and press Enter to open the Registry Editor, then navigate to:
|
||||
|
||||
```text
|
||||
Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList\{old user SID}
|
||||
```
|
||||
|
||||
using the SID you noted in step 1. Double-click `ProfileImagePath` in the right-hand pane and change its value from:
|
||||
|
||||
```text
|
||||
C:\Users\张三
|
||||
```
|
||||
|
||||
to:
|
||||
|
||||
```text
|
||||
C:\Users\JohnDoe
|
||||
```
|
||||
|
||||
Click OK and close the Registry Editor.
|
||||
|
||||
:::warning This is the critical step
|
||||
If you rename the folder but fail to update the registry — or update it incorrectly — your next sign-in will land you in a **temporary profile**: an empty desktop, empty Documents, as though all your data had vanished. It has not; it is still sitting in `C:\Users\JohnDoe`. Go back and check that the SID and `ProfileImagePath` agree, and the profile will mount again.
|
||||
|
||||
Also, if you find two entries under `ProfileList` sharing the same SID, one of them suffixed with `.bak`, that means a profile failed to load at some point. Make sure the correct entry (the one without `.bak`) points at the new folder, then tidy away the duplicate.
|
||||
:::
|
||||
|
||||
## 6. Sign out of the temporary account and restart
|
||||
|
||||
Sign out of the temporary account once more, then restart the computer.
|
||||
|
||||
## 7. Sign back in and let Windows repair the profile
|
||||
|
||||
Sign in with **your original account** (the name on the sign-in screen may still be Chinese; that is dealt with in step 9). As it signs in, Windows detects that the profile path has changed and repairs the profile automatically. You may see messages such as "Getting Windows ready" — wait patiently until it finishes.
|
||||
|
||||
Once you are in, check two things:
|
||||
|
||||
- `C:\Users\JohnDoe` is your profile folder, and your desktop, documents and other personal files are all present;
|
||||
- Open Command Prompt or PowerShell and run `echo %USERPROFILE%`. It should print `C:\Users\JohnDoe`.
|
||||
|
||||
## 8. Fix the paths in the system environment variables
|
||||
|
||||
Right-click `This PC → Properties → Advanced system settings → Environment Variables`, then go through both the **System variables** and the **User variables**, changing every entry that hard-codes the old path from `C:\Users\张三\...` to `C:\Users\JohnDoe\...`.
|
||||
|
||||
Note the distinction:
|
||||
|
||||
- Entries written as `%USERPROFILE%\AppData\...` need **no change** — they are expanded at run time and follow the new folder automatically;
|
||||
- Only **hard-coded absolute paths** need editing, for example `C:\Users\张三\scoop\shims` or `C:\Users\张三\AppData\Local\Programs\Python\Python312`;
|
||||
- `TEMP` and `TMP` are usually of the form `%USERPROFILE%\AppData\Local\Temp` and generally need nothing done to them.
|
||||
|
||||
## 9. Change the account's display name
|
||||
|
||||
Press <Kbd>Win</Kbd> + <Kbd>R</Kbd>, type `control userpasswords2` and press Enter. Select your original account in the list, click **Properties**, change the user name to the new English one, and click OK.
|
||||
|
||||
This step only affects the sign-in screen and the name shown in the interface. It does not change the SID, and it has no bearing on the folder you have already renamed.
|
||||
|
||||
## 10. Remove the temporary account (optional)
|
||||
|
||||
Once you are satisfied that everything works, and that you can still sign in after a restart, delete the go-between account: go to `Settings → Accounts → Other users`, select it, choose **Remove**, then delete the `C:\Users\tempadmin` folder.
|
||||
|
||||
:::tip
|
||||
Restart once and confirm that everything is in order before deleting it, so that you are not left needing the temporary account after it has gone.
|
||||
:::
|
||||
|
||||
## Afterwards: some applications may need reinstalling
|
||||
|
||||
Once the username — and hence the profile folder — changes, any application that has **absolute paths written into its configuration, services, scheduled tasks or shortcuts** may fail to start, or may lose its settings. The usual suspects:
|
||||
|
||||
- **Package managers and runtimes** — Scoop, Chocolatey, Anaconda, nvm, and globally installed Node or Python packages, whose shims and configuration files tend to contain the old path;
|
||||
- **Development tools** — the JetBrains IDEs (whose configuration and cache live under the old path), Docker Desktop, WSL distributions, and Git's global configuration and credential store;
|
||||
- **Anything registered as a Windows service** — databases, web servers and the like, where the service definition pins the absolute paths of the executable and its data directory;
|
||||
- **Desktop shortcuts and the "recently used" lists** — these may all stop working;
|
||||
- **Cloud storage and sync clients** — these will need pointing at the new folder again.
|
||||
|
||||
When that happens, **uninstalling and reinstalling** is usually the least painful and most reliable remedy; a few applications can be put right by re-pointing the paths or running a repair install. It is worth opening each of your everyday development tools after the rename and checking them one by one, reinstalling whatever misbehaves.
|
||||
|
||||
## Summary
|
||||
|
||||
Renaming a Windows username — and in particular the profile folder — is a "pain once, relief for a long time" operation. The process itself is not complicated, but it is sensitive to the order of the steps and the timing of the restarts. Follow the sequence strictly — note the SID, create a temporary account, rename the folder, edit the registry, then come back to fix the environment variables and the display name — and it will go smoothly.
|
||||
|
||||
And once it is done, problems of the kind described in [JetBrains IDE Prompting for the Git User's Password When Cloning over SSH](./jetbrains-git-ssh-clone-password-prompt.md), caused by non-ASCII paths, disappear along with them.
|
||||
|
||||
> Reproduced from a video by Douyin user **@90后科技说**, originally at [https://v.douyin.com/2hqIZUsG9YM/](https://v.douyin.com/2hqIZUsG9YM/).
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: JetBrains IDE 使用 SSH 方式 Git Clone 时提示输入 Git 用户密码的问题
|
||||
tags:
|
||||
- jetbrains
|
||||
- git
|
||||
- ssh
|
||||
- windows
|
||||
author:
|
||||
name: Zihlu Wang
|
||||
email: real@zihluwang.me
|
||||
---
|
||||
|
||||
在 Windows 环境下使用 JetBrains 系列 IDE（例如 IntelliJ IDEA、PyCharm、WebStorm、GoLand 等）开发项目时，如果 Windows 本地用户名使用了中文，在通过 SSH 方式执行 `git clone` 时，有时会遇到一个比较奇怪的问题：
|
||||
|
||||
> 明明配置的是 Git SSH 地址，却一直提示输入 Git 用户的密码。
|
||||
|
||||
例如仓库地址：
|
||||
|
||||
```text
|
||||
git@git.example.com:project/demo.git
|
||||
```
|
||||
|
||||
正常情况下，Git 应该通过 SSH Key 进行身份认证，而不应该要求输入 Git 用户本身的登录密码。
|
||||
|
||||
这种问题在命令行 Git 中可能不明显，但在 JetBrains IDE 中执行 Clone、Pull、Push 等操作时可能出现。
|
||||
|
||||
## 问题表现
|
||||
|
||||
假设 Windows 用户名为：
|
||||
|
||||
```text
|
||||
张三
|
||||
```
|
||||
|
||||
对应的用户目录可能是：
|
||||
|
||||
```text
|
||||
C:\Users\张三
|
||||
```
|
||||
|
||||
在 JetBrains IDE 中选择：
|
||||
|
||||
```text
|
||||
Git → Clone → Repository URL
|
||||
```
|
||||
|
||||
然后填写：
|
||||
|
||||
```text
|
||||
git@git.example.com:project/demo.git
|
||||
```
|
||||
|
||||
点击 Clone 后，可能出现类似提示：
|
||||
|
||||
```text
|
||||
git@git.example.com's password:
|
||||
```
|
||||
|
||||
或者 IDE 弹出密码输入框，要求输入 Git 用户的密码。
|
||||
|
||||
但是即使输入正确的密码，也可能无法完成 Clone。
|
||||
|
||||
## 为什么 SSH 地址还会要求输入密码？
|
||||
|
||||
要理解这个问题，先要理解 SSH 的认证回退机制。
|
||||
|
||||
SSH 登录时，认证方式是按顺序尝试的：
|
||||
|
||||
1. **公钥认证（Public Key）**——客户端拿出本地私钥，服务器检查对应公钥是否在 `~/.ssh/authorized_keys`（Git 服务端则是用户上传的 SSH Key）中;
|
||||
2. **密码 / 键盘交互认证（Password / Keyboard-Interactive）**——如果公钥认证没有通过，服务器会继续询问密码。
|
||||
|
||||
因此，当 IDE 里出现 `git@git.example.com's password:` 时，**问题并不是「没有走 SSH」，而是「公钥认证失败了」**：SSH 客户端没能拿出正确的那把私钥，服务器于是退回到密码认证，向你索要 Git 服务器上 `git` 用户的密码——注意，是 `git` 这个账户的密码，而不是你自己的账号密码。而主流 Git 服务端（GitLab、Gitea 等）默认都禁用了 `git` 用户的密码登录，所以即便输入了正确的密码，Clone 依然会失败。
|
||||
|
||||
问题的根子在于：**客户端没有找到私钥。**
|
||||
|
||||
在中文用户名的 Windows 上，这通常是路径编码导致的。Windows 下私钥默认位于：
|
||||
|
||||
```text
|
||||
C:\Users\张三\.ssh\id_rsa
|
||||
```
|
||||
|
||||
SSH 客户端（无论是 Git for Windows 附带的 OpenSSH，还是 JetBrains IDE 内置的 SSH 实现）需要借助 `%USERPROFILE%` 或 `HOME` 环境变量定位这个目录。当用户名中含有中文等非 ASCII 字符时，这条路径在进程之间传递时容易出现编码不一致（UTF-8 / GBK / ANSI 之间来回转换），最终客户端解析出的 `~/.ssh` 路径与实际路径对不上——`config` 文件和私钥都读不到，也就只能退回密码认证了。
|
||||
|
||||
一个很典型的判断方法：**在系统终端里执行 `ssh -T git@git.example.com` 能正常返回欢迎信息，但在 IDE 里 Clone 却要密码。** 这说明私钥本身没问题，问题只出在 IDE 这一侧的路径解析上。
|
||||
|
||||
## 如何确认
|
||||
|
||||
1. 确认仓库地址用的确实是 SSH 协议（`git@host:path` 或 `ssh://git@host/path`），而不是 HTTP 地址。
|
||||
2. 在终端执行 `ssh -T git@git.example.com`：
|
||||
- 终端一切正常 → 私钥与服务器配置都没问题，问题在 IDE 侧；
|
||||
- 终端也报错 → 先按常规流程排查私钥文件、`~/.ssh/config`、以及公钥是否已上传到服务端。
|
||||
3. 在 IDE 中查看 Git 使用的 SSH 实现：`Settings → Version Control → Git → SSH executable`。
|
||||
4. 检查 `C:\Users\张三\.ssh` 目录是否真实存在、`config` 内容是否被正确读取。
|
||||
|
||||
## 临时绕过方案
|
||||
|
||||
在动手改用户名之前，可以先尝试下面几种绕开非 ASCII 路径的做法。
|
||||
|
||||
### 方案一：改用 Git 自带的 ssh.exe
|
||||
|
||||
JetBrains IDE 默认可能使用内置的 SSH 实现。把 `Settings → Version Control → Git → SSH executable` 改为 `Native`（即使用 Git for Windows 附带的 `ssh.exe`），然后重试 Clone。切换实现后路径解析的行为不同，往往能直接绕开这个问题。
|
||||
|
||||
### 方案二：把密钥放到纯 ASCII 路径下并显式指定
|
||||
|
||||
将密钥目录从 `C:\Users\张三\.ssh` 复制到 `C:\ssh`，再让 Git 显式使用这个目录下的私钥与 known_hosts：
|
||||
|
||||
```shell
|
||||
git config --global core.sshCommand "ssh -i C:/ssh/id_rsa -o UserKnownHostsFile=C:/ssh/known_hosts"
|
||||
```
|
||||
|
||||
配置后，命令行 Git 以及所有调用系统 Git 的 IDE 都会走这条命令，不再依赖 `~/.ssh` 的自动推导。
|
||||
|
||||
### 方案三：为 IDE 单独设置 HOME 环境变量
|
||||
|
||||
创建一个纯 ASCII 的家目录（例如 `C:\ssh-home`），把密钥放到 `C:\ssh-home\.ssh\` 下，然后在 IDE 使用的环境变量中设置：
|
||||
|
||||
```text
|
||||
HOME=C:\ssh-home
|
||||
```
|
||||
|
||||
这样 SSH 就会去 `C:\ssh-home\.ssh\` 里查找配置与私钥，完全避开中文路径。
|
||||
|
||||
> 三种方案都能缓解问题，但本质上都是「打补丁」。只要用户名还是中文，其它的软件——Node、Python、Docker、各类 CLI 工具——仍可能因为同样的原因踩坑。**根本的解决办法是把 Windows 用户名改成英文**，具体步骤见 [将 Windows 用户名修改为英文](./rename-windows-user-profile-to-english.mdx)。
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
title: 将 Windows 用户名（用户目录）修改为英文的完整步骤
|
||||
tags:
|
||||
- windows
|
||||
- user-profile
|
||||
- registry
|
||||
- troubleshooting
|
||||
author:
|
||||
name: Zihlu Wang
|
||||
email: real@zihluwang.me
|
||||
---
|
||||
|
||||
import { Kbd } from "@rspress/core/theme"
|
||||
|
||||
在 Windows 上使用中文用户名，系统本身能正常工作，却会给不少开发工具添麻烦——最典型的就是 [JetBrains IDE 用 SSH 方式 Clone 时反复要求输入密码](./jetbrains-git-ssh-clone-password-prompt.md)。根源在于用户目录 `C:\Users\张三` 里的非 ASCII 字符：Git、Node、Python、Docker 以及各类 CLI 工具在读取这条路径时各用各的编码，稍有不慎就会解析失败。
|
||||
|
||||
把用户名改成英文可以一劳永逸地解决这类问题。整个过程不算复杂，但对**步骤顺序**和**重启时机**比较敏感，下面按顺序逐步说明。
|
||||
|
||||
:::warning 开始之前
|
||||
|
||||
本文的操作会修改**注册表**和**用户配置文件目录**，属于有风险的操作。动手前请务必：
|
||||
|
||||
- 备份重要数据（尤其是桌面、文档、以及各类软件的配置目录）；
|
||||
- 确认当前账户拥有**管理员权限**；
|
||||
- 建议先创建一个系统还原点，以便中途出问题时回退；
|
||||
- 严格按本文的顺序执行，不要跳步，尤其是重启的时机。
|
||||
|
||||
:::
|
||||
|
||||
## 整体思路
|
||||
|
||||
Windows 里的「用户名」其实对应两样东西：
|
||||
|
||||
1. **账户显示名**——登录界面、开始菜单上看到的名字；
|
||||
2. **用户配置文件目录名**——`C:\Users\<名字>` 这一层文件夹。
|
||||
|
||||
麻烦之处在于：Windows 不允许在用户处于登录状态时重命名它的配置文件目录；同时注册表里记录了这个目录的**绝对路径**，光改文件夹名而不改注册表，会导致下次登录时挂载不到原配置文件。
|
||||
|
||||
因此需要借助一个「过渡账户」来完成：
|
||||
|
||||
> 建临时账户 → 用它登录 → 改文件夹名 → 改注册表 → 回到原账户。
|
||||
|
||||
## 一、获取现有用户的 SID
|
||||
|
||||
以当前（中文用户名的）账户登录，打开 PowerShell 或命令提示符，执行：
|
||||
|
||||
```powershell
|
||||
whoami /user
|
||||
```
|
||||
|
||||
输出类似：
|
||||
|
||||
```text
|
||||
用户信息
|
||||
------------------
|
||||
用户名 SID
|
||||
================= ============================================
|
||||
desktop-abc\张三 S-1-5-21-1234567890-1234567890-1234567890-1001
|
||||
```
|
||||
|
||||
记下结尾那串 `S-1-5-21-...-1001`，它就是后面要找的 `{旧用户 SID}`。
|
||||
|
||||
如果想一次列出所有本地账户及其 SID，可以用：
|
||||
|
||||
```powershell
|
||||
wmic useraccount get name,sid
|
||||
|
||||
# 或在较新版本的 PowerShell 中：
|
||||
Get-LocalUser | Select-Object Name, SID
|
||||
```
|
||||
|
||||
## 二、创建一个新的本地 Windows 用户
|
||||
|
||||
打开 `设置 → 账户 → 其他用户 → 添加账户`，在「如何登录？」这一步选择 **「我没有这个人的登录信息」**，接着选择 **「添加一个没有 Microsoft 帐户的用户」**，创建一个纯英文名的**本地账户**，例如 `tempadmin`。
|
||||
|
||||
创建完成后，在「其他用户」列表中选中该账户，进入「更改账户类型」，把它**提升为管理员**。
|
||||
|
||||
这个账户只是「过渡用」的，作用是让我们能在**原账户已注销**的状态下，去操作它的文件与注册表。
|
||||
|
||||
## 三、注销当前用户，登录新创建的账户
|
||||
|
||||
保存好手头的工作，注销当前账户，重启电脑，然后用刚才创建的临时账户登录。
|
||||
|
||||
## 四、重命名用户目录
|
||||
|
||||
在临时账户下打开**文件资源管理器**，进入 `C:\Users`，把 `张三` 重命名为你想要的英文名（例如 `JohnDoe`）：
|
||||
|
||||
```text
|
||||
C:\Users\张三 → C:\Users\JohnDoe
|
||||
```
|
||||
|
||||
如果提示「文件夹正在使用」，说明原账户还有进程在运行（后台服务、同步网盘、常驻程序等）。可以先彻底重启再试，或者改用命令行重命名：
|
||||
|
||||
```powershell
|
||||
Rename-Item -Path "C:\Users\张三" -NewName "JohnDoe"
|
||||
```
|
||||
|
||||
:::tip 命名建议
|
||||
新名字建议只用英文字母和数字，并且不要带空格。虽然 `C:\Users\zhang san` 也能用，但空格同样会让部分命令行工具出问题。
|
||||
:::
|
||||
|
||||
## 五、修改注册表中的 ProfileImagePath
|
||||
|
||||
按 <Kbd>Win</Kbd> + <Kbd>R</Kbd>，输入 `regedit` 回车，打开注册表编辑器，定位到：
|
||||
|
||||
```text
|
||||
Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList\{旧用户 SID}
|
||||
```
|
||||
|
||||
也就是第一步记下的那串 SID 对应的项。双击右侧的 `ProfileImagePath`，把「数值数据」从：
|
||||
|
||||
```text
|
||||
C:\Users\张三
|
||||
```
|
||||
|
||||
改为：
|
||||
|
||||
```text
|
||||
C:\Users\JohnDoe
|
||||
```
|
||||
|
||||
确定后关闭注册表编辑器。
|
||||
|
||||
:::warning 这一步最关键
|
||||
如果目录名改了、注册表却没改（或改错），下次登录会进入一个**临时配置文件**——桌面空白、文档为空，看起来像「用户数据全丢了」。其实数据还在 `C:\Users\JohnDoe` 里，只要回头核对 SID 与 `ProfileImagePath` 是否一致就能恢复。
|
||||
|
||||
另外，如果 `ProfileList` 下出现了两个相同 SID 的项，其中一个是带 `.bak` 后缀，说明此前发生过配置文件加载失败。此时应确保正确的那一项（不带 `.bak`）的 `ProfileImagePath` 指向新目录，并把重复项清理掉。
|
||||
:::
|
||||
|
||||
## 六、注销临时账户并重启
|
||||
|
||||
再次注销临时账户，然后重启电脑。
|
||||
|
||||
## 七、登录原账户，等待 Windows 自动修复
|
||||
|
||||
用**原来的账户**登录（此时登录界面显示的名字可能还是中文，下一步再改）。登录过程中 Windows 会检测到配置文件路径的变化并自动修复，期间可能出现「正在准备 Windows」之类的提示，耐心等待它完成。
|
||||
|
||||
登录后确认两件事：
|
||||
|
||||
- `C:\Users\JohnDoe` 是你的用户目录，桌面、文档等个人文件都在；
|
||||
- 打开命令提示符或 PowerShell 执行 `echo %USERPROFILE%`，输出应为 `C:\Users\JohnDoe`。
|
||||
|
||||
## 八、修正系统环境变量中的路径
|
||||
|
||||
右键 `此电脑 → 属性 → 高级系统设置 → 环境变量`，逐条检查**系统变量**与**用户变量**，把所有硬编码了旧路径的项，从 `C:\Users\张三\...` 改为 `C:\Users\JohnDoe\...`。
|
||||
|
||||
判断时注意区分：
|
||||
|
||||
- 形如 `%USERPROFILE%\AppData\...` 的项**不用改**，它会在运行时展开，会自动指向新目录；
|
||||
- 只有**写死的绝对路径**才需要改，例如 `C:\Users\张三\scoop\shims`、`C:\Users\张三\AppData\Local\Programs\Python\Python312`；
|
||||
- 用户变量里的 `TEMP`、`TMP` 通常是 `%USERPROFILE%\AppData\Local\Temp` 形式，一般无需修改。
|
||||
|
||||
## 九、修改账户的显示名
|
||||
|
||||
按 <Kbd>Win</Kbd> + <Kbd>R</Kbd>，输入 `control userpasswords2` 回车。在弹出的用户列表中选中原账户那一行，点击 **属性**，把「用户名」改为新的英文名，确定即可。
|
||||
|
||||
这一步只影响登录界面和界面里显示的名称，不改变 SID，也不会影响前面已经改好的目录。
|
||||
|
||||
## 十、清理临时账户（可选）
|
||||
|
||||
确认一切正常、重启后仍能正常登录之后，可以把过渡用的临时账户删掉：进入 `设置 → 账户 → 其他用户`，选中它并选择「删除」，再删掉 `C:\Users\tempadmin` 目录。
|
||||
|
||||
:::tip
|
||||
删除前建议先重启一次并确认新账户一切正常，免得删完才发现还有问题需要回过头来用临时账户。
|
||||
:::
|
||||
|
||||
## 改完之后：部分软件可能需要重装
|
||||
|
||||
用户名（用户目录）变更后，凡是把**绝对路径写进配置、服务、计划任务或快捷方式**的软件，都可能因为路径失效而无法启动或丢失配置。常见需要留意的有：
|
||||
|
||||
- **包管理器与运行时**——Scoop、Chocolatey、Anaconda、nvm，以及全局安装的 Node / Python 包，它们的 shims 和配置文件里往往写着旧路径；
|
||||
- **开发工具**——JetBrains 系列 IDE（配置与缓存目录就位于旧路径下）、Docker Desktop、WSL 发行版、Git 的全局配置与凭据存储；
|
||||
- **注册为服务的程序**——数据库、Web 服务器等，Windows 服务里通常固化了可执行文件与数据目录的绝对路径；
|
||||
- **桌面快捷方式与「最近使用」列表**——可能全部失效；
|
||||
- **各类云盘 / 同步客户端**——需要重新指定本地目录。
|
||||
|
||||
遇到这类情况时，**卸载后重新安装**通常是最省事、最可靠的处理方式；少数软件也可以通过重新指定路径或「修复安装」解决。建议改完用户名后，把日常使用的开发工具逐个打开验证一遍，发现异常就重装。
|
||||
|
||||
## 小结
|
||||
|
||||
把 Windows 用户名（尤其是用户目录）改成英文，是一次「一次疼、长期省」的操作：流程本身不复杂，但对步骤顺序和重启时机比较敏感。只要严格按顺序来——记 SID、建临时账户、改目录、改注册表、回来修正环境变量与显示名——就能顺利完成。
|
||||
|
||||
改完之后，[JetBrains IDE 用 SSH Clone 时要求输入密码](./jetbrains-git-ssh-clone-password-prompt.md) 这类由非 ASCII 路径引起的问题也会一并消失。
|
||||
|
||||
> 本文转载整理自抖音用户 **@90后科技说**，原视频地址：[https://v.douyin.com/2hqIZUsG9YM/](https://v.douyin.com/2hqIZUsG9YM/)
|
||||
+8
-1
@@ -138,11 +138,18 @@ function bareRoutePath(localePrefix: (lang: string) => string, routePath: string
|
||||
*
|
||||
* It cannot live in `docs/public/`, because a single static file would have to
|
||||
* carry the wrong origin for one of the two targets.
|
||||
*
|
||||
* Rspress also runs `afterBuild` in dev, after each recompile. Dev never creates
|
||||
* the output directory, so the write would fail with `ENOENT` — hence the
|
||||
* `isProd` guard, which comes from the hook rather than `NODE_ENV`.
|
||||
*/
|
||||
function pluginRobots(origin: string): RspressPlugin {
|
||||
return {
|
||||
name: "plugin-onixbyte-robots",
|
||||
async afterBuild(config: UserConfig) {
|
||||
async afterBuild(config: UserConfig, isProd: boolean) {
|
||||
if (!isProd) {
|
||||
return
|
||||
}
|
||||
const outDir = path.resolve(process.cwd(), config.outDir ?? "doc_build")
|
||||
const body = ["User-agent: *", "Allow: /", "", `Sitemap: ${origin}/sitemap.xml`, ""].join(
|
||||
"\n"
|
||||
|
||||
Reference in new issue
Block a user