path: root/Master/texmf-dist/doc/latex/install-latex-guide-zh-cn/chapter/windows.tex

% !TeX root = ../install-latex-guide-zh-cn.tex

\chapter{Windows 11 系统}

\section{安装 \TeX{} Live}\label{sec:windows:install}

在安装 \TeX{} Live 之前,
在文件夹菜单栏 \menu{查看 > 显示} 中选择 \menu{文件扩展名}.

用户可以从最近的 CTAN 源\footnote{这里所谓的最近, 其实是由系统判定的, 实际上系统可能会误判}下载 \TeX{} Live 的
\href{https://mirrors.ctan.org/systems/texlive/Images/texlive2024.iso}{iso 镜像文件},
也可以找大陆地区的源自行下载\footnote{新版本发布时, 各镜像网站同步的进度会有不同}.
通过大陆地区的源下载 iso 文件的方法请参考附录~\ref{chp:appendix:mirror}.

假设镜像文件被下载到本地后,
其存放路径为 \texttt{X:\textbackslash Y}%
\footnote{这里, \texttt{X} 表示盘符,
如 \texttt{C}、\texttt{D}、\texttt{E} 等;
\texttt{Y} 表示文件夹;
默认路径名称为不带空格的英文}.
下载完毕后, 用户打开 \textsf{cmd} 窗口%
\footnote{点击 \keys{\faWindows},
输入 \textsf{cmd},
点击 \keys{\enter};
或在任意文件夹中按 \keys{\ctrl + L},
输入 \textsf{cmd},
点击 \keys{\enter}},
执行
\begin{lstlisting}[language = bash]
  echo %path:;=&echo.%
\end{lstlisting}
查看环境变量. 
若 \texttt{C:\textbackslash Windows\textbackslash system32}
不在结果中\footnote{这里默认系统盘为\textsf{C}盘},
则关闭 \textsf{cmd} 窗口,
将 \texttt{C:\textbackslash Windows\textbackslash system32}
添加到环境变量中\footnote{在 \menu{桌面 > 此电脑 > 属性 > 高级系统设置 > 环境变量 > 系统变量 > Path} 中添加}.
\textbf{根据以往经验, 安装过 C\TeX{} 套装的用户往往会有} \texttt{system32} \textbf{丢失的问题}. 
另外, 如果环境变量中有 \texttt{mingw} 或 \texttt{jdk} 相关的内容,
也请暂时删除\footnote{具体原因参见
\href{https://tex.stackexchange.com/questions/445086/error-installing-latest-version-of-tex-live-on-windows-10}{stackexchange} 
的解释, 待安装结束后, 再将 \texttt{mingw} 或 \texttt{jdk} 环境变量添加至 \TeX{} Live 的环境变量之后}.
同时国内常见的 2345 好压也会对安装构成影响,
建议删除它并在安装 \TeX{} Live 后更换其他同类软件%
\footnote{推荐 \href{http://www.winrar.com.cn/}{WinRAR}
或 \href{https://www.7-zip.org/}{7-Zip}}.

下面我们要确保下载到的 iso 文件没有损坏, 一种常用做法是检查其 MD5 值.
当然, 如果确信自己下载到的文件没有问题, 也可以跳过这一步.
打开 \textsf{cmd} 窗口依次执行以下代码
\begin{lstlisting}[language = bash]
  cd /d X:\Y
  certutil -hashfile texlive2024.iso md5
\end{lstlisting}
若系统显示
\begin{lstlisting}
  MD5 的 texlive2024.iso 哈希:
  a54f5524e51267dee37e72e3b3fd31c4
  CertUtil: -hashfile 命令成功完成.
\end{lstlisting}
则表明下载的镜像文件正常.
除 MD5 值外,
还可检查 SHA512 值.
依然是在 \textsf{cmd} 执行
\begin{lstlisting}[language = bash]
  cd /d X:\Y
  certutil -hashfile texlive2024.iso sha512
\end{lstlisting}
若系统显示
\begin{lstlisting}[language=bash,literate={a}{a}{1} {b}{b}{1} {c}{c}{1} {d}{d}{1} {e}{e}{1} {f}{f}{1}]
  SHA512 的 texlive2024.iso 哈希:
  6e3c3470ee5ca903bb5c31f436b018cd2cfbc526c4ca563ccb15959802f8b1a6c0475c58566c1afaba19dc780fd192ac5511818ef5a89828d935c66c62cfcb2a
  CertUtil: -hashfile 命令成功完成.
\end{lstlisting}
即为验证成功.

接下来开始安装.
推荐用户先手动建立 \TeX{} Live 的安装路径 (文件夹) 再进行安装,
注意路径的名称是\textbf{不带空格的英文},
默认路径为 \texttt{C:\textbackslash texlive\textbackslash 2024}.
假如系统用了中文作为用户名,
那么用户需要先按照 \ref{sec:chinesename} 节的方法更改临时环境变量后再安装.
将镜像文件装载至虚拟光驱\footnote{Windows 11 默认双击镜像文件便可装载;
受某些压缩软件影响双击失效时,
可在文件夹菜单栏
\menu{装载};
第三方虚拟光驱软件可考虑 WinCDEmu 或 UltraISO;
不鼓励解压缩镜像文件}. 
假设加载后的路径为 \texttt{Z:\textbackslash}.
在卸载了国内第三方安全软件的前提下,
打开 \textsf{cmd} 窗口并执行
\begin{lstlisting}[language = bash]
  Z:\install-tl-windows.bat --no-gui
\end{lstlisting}
即可看到如下结果
\begin{lstlisting}
  ======================> TeX Live installation procedure <=====================

  ======>   Letters/digits in <angle brackets> indicate   <=======
  ======>   menu items for actions or customizations      <=======
  = help>   https://tug.org/texlive/doc/install-tl.html   <=======

   Detected platform: Windows (64-bit)

   <B> set binary platforms: 1 out of 15

   <S> set installation scheme: scheme-full

   <C> set installation collections:
       41 collections out of 41, disk space required: 8578 MB (free: 230119 MB)

   <D> set directories:
     TEXDIR (the main TeX directory):
       C:/texlive/2024
     TEXMFLOCAL (directory for site-wide local files):
       C:/texlive/texmf-local
     TEXMFSYSVAR (directory for variable and automatically generated data):
       C:/texlive/2024/texmf-var
     TEXMFSYSCONFIG (directory for local config):
       C:/texlive/2024/texmf-config
     TEXMFVAR (personal directory for variable and automatically generated data):
       ~/.texlive2024/texmf-var
     TEXMFCONFIG (personal directory for local config):
       ~/.texlive2024/texmf-config
     TEXMFHOME (directory for user-specific files):
       ~/texmf

   <O> options:
     [ ] use letter size instead of A4 by default
     [X] allow execution of restricted list of programs via \write18
     [X] create all format files
     [X] install macro/font doc tree
     [X] install macro/font source tree
     [X] adjust search path
     [1] add menu items, shortcuts, etc.
     [1] update file associations
     [X] install TeXworks front end
     [X] after install, set CTAN as source for package updates

   <V> set up for portable installation

  Actions:
   <I> start installation to hard disk
   <P> save installation profile to 'texlive.profile' and exit
   <Q> quit

  Enter command:
\end{lstlisting}
这时, 用户可可直接按键盘 \keys{I} 在默认路径中直接安装 \TeX{} Live,
也可按键盘 \keys{D} 来更改安装路径.
按 \keys{D} 后, 用户可看到
\begin{lstlisting}
  ==============================================================================
  Directories customization:
  
  <1> TEXDIR:       C:/texlive/2024
      main tree:    C:/texlive/2024/texmf-dist
  
  <2> TEXMFLOCAL:     C:/texlive/texmf-local
  <3> TEXMFSYSVAR:    C:/texlive/2024/texmf-var
  <4> TEXMFSYSCONFIG: C:/texlive/2024/texmf-config
  
  <5> TEXMFVAR:       ~/.texlive2024/texmf-var
  <6> TEXMFCONFIG:    ~/.texlive2024/texmf-config
  <7> TEXMFHOME:      ~/texmf
  
  Note: ~ will expand to %USERPROFILE%
  
  Actions:
  <R> return to main menu
  <Q> quit
  
  Enter command:
\end{lstlisting}
这时按键盘 \keys{1}, 将看到
\begin{lstlisting}
  New value for TEXDIR [C:/texlive/2024]:
\end{lstlisting}
这时可更改路径, 如 \texttt{D:/texlive/2024}.
接下来, 按键盘 \keys{R} 即可回到初始的安装界面,
再按键盘 \keys{I} 便可在刚才指定的路径安装.
用户可通过阅读英文执行其他操作, 这里不再赘述. 
至此, 用户只需耐心等待安装完成, 并且不要点击 \textsf{cmd} 窗口%
\footnote{Windows 11 默认采取快速编辑模式, 一旦点击 \textsf{cmd} 窗口,
将显示``选择命令提示符''而导致进程暂停}. 
安装完成后, 关闭再打开 \textsf{cmd} 窗口%
\footnote{正常安装 \TeX{} Live 后, 环境变量会变化,
关闭原 \textsf{cmd} 窗口再重新打开才能获取新的环境变量},
执行
\begin{lstlisting}[language = bash]
  tex -v
\end{lstlisting}
显示
\begin{lstlisting}
  TeX 3.141592653 (TeX Live 2024)
  kpathsea version 6.4.0
  Copyright 2024 D.E. Knuth.
  There is NO warranty.  Redistribution of this software is
  covered by the terms of both the TeX copyright and
  the Lesser GNU General Public License.
  For more information about these matters, see the file
  named COPYING and the TeX source.
  Primary author of TeX: D.E. Knuth.
\end{lstlisting}
即可认为安装顺利完成%
\footnote{若未能正确显示结果, 则可能是因为环境变量未改变,
用户可手动添加 \texttt{<TEXDIR>\textbackslash bin\textbackslash windows} 至环境变量,
\texttt{<TEXDIR>} 需与你方才的安装路径一致}.
弹出前面装载的光盘镜像,
安装到此结束.

\subsection{下载镜像一直不成功的处理办法}

目前发现有些用户使用某些浏览器时无法正常下载镜像文件.
这时,
用户可以选择使用 \href{https://eternallybored.org/misc/wget/}{\textsf{wget}} 对镜像进行下载.
具体用法是:
将 \textsf{wget} 所在目录添加到环境变量中.
打开 \textsf{cmd} 窗口执行以下代码
\begin{lstlisting}[language = bash]
  wget http://mirrors.ctan.org/systems/texlive/Images/texlive2024.iso
\end{lstlisting}
即可下载最近的镜像.
类似地,
也可以指定国内的源进行下载,
例如选择清华大学镜像
\begin{lstlisting}[language = bash]
  wget https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/Images/texlive2024.iso
\end{lstlisting}
其他国内镜像只需要将链接替换即可,
链接和方法请参考附录~\ref{chp:appendix:mirror}.

\subsection{需要管理员权限的处理办法}

有些用户反馈安装过程中需要管理员权限.
以管理员身份打开 \textsf{cmd} 窗口的方法是点击 \keys{\faWindows},
输入 \textsf{cmd},
按 \keys{\ctrl + \shift + \enter} 三个键.
一般而言,
在系统盘内直接安装 \TeX{} Live 会碰到此类问题,
因此鼓励用户在安装前先手动建立安装路径.
直接使用管理员身份打开 \textsf{cmd} 窗口进行安装可能会对以后的升级造成影响.

\subsection{系统用中文作为用户名}\label{sec:chinesename}

很多中文 Windows 用户习惯于用中文作为用户名,
但是这样会导致 \TeX{} Live 安装失败.
更改系统的 \texttt{TEMP} 和 \texttt{TMP} 这两个环境变量可以避免这样的问题.
在 \textsf{cmd} 中执行
\begin{lstlisting}
  mkdir C:\temp
  set TEMP=C:\temp
  set TMP=C:\temp
\end{lstlisting}
便可更改这两个环境变量为 \texttt{C:\textbackslash temp}.
更改后按照前述内容安装 \TeX{} Live 即可.
这样的更改是临时的,
待 \textsf{cmd} 窗口关闭,
环境变量将恢复为原始状态.

\section{卸载 \TeX{} Live}

在跨版本升级 \TeX{} Live 时, 通常需要卸载旧版 \TeX{} Live.
下面介绍几种卸载方法.

\subsection{使用批处理文件}

在命令行执行
\begin{lstlisting}[language=bash]
  kpsewhich -var-value TEXMFROOT
\end{lstlisting}
可以查看 \texttt{TEXMFROOT} 的值,
该值即为 \TeX{} Live 的安装路径%
\footnote{%
  除这里提供的 \texttt{TEXMFROOT}, 还有很多其他变量, 可在
  \href{https://www.tug.org/texlive/doc/texlive-zh-cn/texlive-zh-cn.pdf}{texlive-zh-cn}
  第 2.3 节处找到
}. 
接下来,
用户只需执行%
\footnote{双击或在 \texttt{cmd} 中运行}%
安装路径中的卸载批处理文件即可实现卸载, 如默认安装时执行
\begin{lstlisting}[language=bash]
  C:\texlive\2024\tlpkg\installer\uninst.bat
\end{lstlisting}
结束以上步骤后,
手动删除用户文件夹中的 \texttt{.texlive2024}.
如果用户安装 \TeX{} Live 时需要管理员权限,
那么在卸载时同样需要管理员权限.

卸载后,
用户需要清理注册表
\begin{lstlisting}
  HKEY_CURRENT_USER\Software\Classes\TL.bitmap2eps.convert.2024
  HKEY_CURRENT_USER\Software\Classes\TL.DVIOUT.view.2024
  HKEY_CURRENT_USER\Software\Classes\TL.TeXworks.edit.2024
  HKEY_CURRENT_USER\Software\Classes\TL.PSViewer.view.2024
  HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\ApplicationAssociationToasts\TL.bitmap2eps.convert.2024_.jpg
  HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\ApplicationAssociationToasts\TL.bitmap2eps.convert.2024_.png
  HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\ApplicationAssociationToasts\TL.TeXworks.edit.2024_.sty
  HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\ApplicationAssociationToasts\TL.TeXworks.edit.2024_.tex
\end{lstlisting}
但若在安装时使用管理员权限``为所有人安装'',
则注册表位置将变为
\begin{lstlisting}
  HKEY_LOCAL_MACHINE\SOFTWARE\Classes\TL.bitmap2eps.convert.2024
  HKEY_LOCAL_MACHINE\SOFTWARE\Classes\TL.DVIOUT.view.2024
  HKEY_LOCAL_MACHINE\SOFTWARE\Classes\TL.TeXworks.edit.2024
  HKEY_LOCAL_MACHINE\SOFTWARE\Classes\TL.PSViewer.view.2024
\end{lstlisting}

\subsection{手动卸载}

如果执行批处理文件 \texttt{uninst.bat} 出错,
用户也可手动删除安装文件夹,
之后再清理 \TeX{} Live 的环境变量,
并且清理注册表.

\section{跨版本升级 \TeX{} Live}

目前在 \href{https://www.tug.org/texlive/upgrade.html}{tug.org}
上面提供的说法是:
Windows 没有类似 Unix 的升级程序,
需要进行新安装%
\footnote{原文是: There is no comparable upgrade procedure for Windows.
Doing a new installation is necessary.}.

\section{升级宏包}\label{sec:windows:update}

安装完成后, 用户可以升级宏包以获得更好的使用体验. 
下面将介绍使用命令行升级宏包的方法. 
打开 \textsf{cmd} 窗口, 首先执行下面命令指定升级使用的镜像源. 
\texttt{ctan} 表示系统在升级时将自动寻求最近的源进行下载. 
\begin{lstlisting}[language=bash]
  tlmgr option repository ctan
\end{lstlisting}
用户同样可以指定其他的镜像源,
方法见附录~\ref{chp:appendix:mirror}.

接下来, 用户执行命令
\begin{lstlisting}[language=bash]
  tlmgr update --list
\end{lstlisting}
可查看目前源上可升级的宏包都有哪些. 
高级用户可以根据自己的需求选择升级特定宏包.
建议初级用户直接升级全部宏包. 
用户只需执行
\begin{lstlisting}[language=bash]
  tlmgr update --self --all
\end{lstlisting}
同时升级 \texttt{tlmgr} 本身和全部宏包. 

\subsection{\texttt{tlmgr} 本身无法成功升级}

遇到这种情况时, 用户需自行下载
\href{https://mirrors.ctan.org/systems/texlive/tlnet/update-tlmgr-latest.exe}{update-tlmgr-latest.exe},
然后再执行升级命令即可%
\footnote{这里依旧让系统自动选择镜像源,
用户可以自行选择国内镜像以加快下载速度}. 

\subsection{升级到一半停止}

这种情况下, 用户需要执行另外一个命令继续升级
\begin{lstlisting}
  tlmgr update --reinstall-forcibly-removed --all
\end{lstlisting}

\subsection{升级宏包的必要性}

自本手册撰写以来,
每年镜像文件打包时都可能存在一些问题,
具体讨论见%
\href{https://github.com/CTeX-org/ctex-kit/issues/569}{这里}.
用户安装完毕后,
请按照本节提供的方法升级.

\section{安装宏包}

在默认状态下, 用户将完整安装 \TeX{} Live, 因此用户极少碰到需要手动安装宏包的情形. 
同时, 在
\href{http://mirrors.ctan.org/info/lshort/chinese/lshort-zh-cn.pdf}{lshort-zh-cn}
中也明确提到, \textbf{如非万不得已, 尽量不要手动安装宏包}. 
因此在这里我只介绍从源处安装宏包的命令. 
假设用户想安装 \texttt{mcmthesis} 宏包, 只需在 \textsf{cmd} 执行
\begin{lstlisting}[language=bash]
  tlmgr install mcmthesis
\end{lstlisting}
需要注意的是, 用户一定要清楚所要安装的宏包名称, 并且在安装宏包前先确保镜像源设置正确.

\section{调出宏包手册}

当正确安装后,
用户可以调出宏包手册以查阅相应内容.
例如在 \textsf{cmd} 执行
\begin{lstlisting}[language=bash]
  texdoc texlive-zh-cn
\end{lstlisting}
或
\begin{lstlisting}[language=bash]
  texdoc lshort-zh-cn
\end{lstlisting}
就可分别调出 \texttt{texlive-zh-cn.pdf} 和 \texttt{lshort-zh-cn.pdf},
这两本手册中都有讲解安装的相关内容,
建议用户阅读.

本手册业已被 \TeX{} Live 收录,
调出本手册的命令为
\begin{lstlisting}[language=bash]
  texdoc install-latex-guide-zh-cn
\end{lstlisting}

\section{编译文档}\label{sec:windows:compile}

升级宏包完成后, 用户可以编译文档. 
这里依旧使用命令行来完成这一过程. 

首先, 用户需要在指定位置\footnote{以下称工作路径}建立一个 \texttt{tex} 文件：
\begin{lstlisting}[language = bash]
  mkdir D:\work-latex
  cd /d D:\work-latex
  notepad main.tex
\end{lstlisting}
第1行表示创建一个工作路径 \texttt{D:\textbackslash work-latex},
第2行表示进入工作路径, 第3行表示用记事本打开 \texttt{main.tex} 文件,
若文件不存在, 系统将询问用户是否创建该文件%
\footnote{Windows 11 对中文名变得友好一些了,
但这里不建议用户使用中文命名工作路径和文件名}.
在打开的记事本中编写一个最小示例
\begin{lstlisting}[language={[LaTeX]TeX}]
  \documentclass{article}
  \begin{document}
    Hello \LaTeX{} World!
  \end{document}
\end{lstlisting}
保存并退出. 
接下来执行
\begin{lstlisting}[language=bash]
  pdflatex main
\end{lstlisting}
等待系统完成编译过程. 
待编译完成后, 我们即可看到在 \texttt{D:\textbackslash work-latex}
中出现了 \texttt{main.pdf} 文件和其他同名的辅助文件
\texttt{main.aux} 与 \texttt{main.log}. 

对于中文文档, 可以在记事本中编写以下最小示例%
\footnote{自 Windows 10 1903 版本开始, 记事本默认使用 UTF-8 编码;
Windows 11 继承了这个特性.
若使用其他编辑器,
请注意规定文档编码为 UTF-8}%
\begin{lstlisting}[language={[LaTeX]TeX}]
  \documentclass[UTF8,fontset=windows]{ctexart}
  \begin{document}
    你好 \LaTeX{} 世界！
  \end{document}
\end{lstlisting}
保存并退出.
接下来执行
\begin{lstlisting}[language=bash]
  xelatex main
\end{lstlisting}
等待系统完成编译过程.
\texttt{xelatex} 编译命令配合 UTF-8 编码和 \texttt{ctex}
宏集已经是\textbf{目前主流的中文处理手段}.
\texttt{xelatex} 可以使用系统内安装的字体,
用户在安装字体时需右键字体文件的快捷菜单 \menu{显示更多选项 > 为所有用户安装}.

总结一下, 在使用 \LaTeX{} 时, 用户首先要在工作路径%
\footnote{建议不同的工程放入不同的工作路径}%
中建立一个完整的 \texttt{tex} 文件%
\footnote{该文件必须包含 \texttt{\textbackslash documentclass},
\texttt{\textbackslash begin\{document\}} 和
\texttt{\textbackslash end\{document\}},
这里不讨论包含子文件的情况,
文件名需为不含空格的英文}.
当 \texttt{tex} 文件内容确定后, 再保存文件并使用编译命令%
\footnote{目前常用的编译命令为 \texttt{pdflatex} 和 \texttt{xelatex}},
将 \texttt{tex} 文件编译成 \texttt{pdf} 文件. 

编译命令有很多可选参数, 如用户能够从 \texttt{pdf} 文件跳回 \texttt{tex} 文件,
便是因为执行编译时添加了参数
\begin{lstlisting}[language=bash]
  pdflatex -synctex=1 main
\end{lstlisting}
有些编译还需要额外调用系统命令,
例如使用 \textsf{minted} 包就有这类要求,
因此可以在执行编译时添加参数
\begin{lstlisting}[language=bash]
  pdflatex -shell-escape main
\end{lstlisting}
此外还有很多其他参数, 用户若感兴趣, 可自行阅读手册. 

在很多时候, 我个人更倾向于使用 \texttt{latexmk} 来编译 \texttt{tex} 文档,
如执行
\begin{lstlisting}[language=bash]
  latexmk -pdf -synctex=1 -interaction=nonstopmode main
\end{lstlisting}
意味着使用 
\begin{lstlisting}[language=bash]
  pdflatex -synctex=1 -interaction=nonstopmode main
\end{lstlisting}
来编译文档 \texttt{main.tex}, 并在有需要时完成其他步骤%
\footnote{如使用 \texttt{bibtex} 或 \texttt{biblatex} 处理参考文献时需要多次编译,
详情见相关文档}. 

\subsection{\LaTeXe 版本不匹配导致 \texttt{xelatex} 失败}

使用 \texttt{xelatex} 编译文档,
系统有时会提示目前 \LaTeXe 的版本低于某宏包的要求版本.
这种情况是由于 \textsf{fmt} 文件未能更新所导致.
此时可考虑在命令行运行
\begin{lstlisting}[language=bash]
  fmtutil-user --byfmt xelatex
\end{lstlisting}
待结束后再用 \texttt{xelatex} 编译文档.
更多内容参考
\href{https://github.com/CTeX-org/forum/issues/70}{github 上的讨论}.

另外也可考虑重装 \texttt{xetex}.
在命令行执行
\begin{lstlisting}[language=bash]
  tlmgr install --reinstall xetex
\end{lstlisting}

\subsection{编译出现 \texttt{l3backend-*} 问题}

这是 \texttt{fmt} 文件未能更新所导致的问题.
可以用
\begin{lstlisting}[language=bash]
  fmtutil-sys --all
\end{lstlisting}
刷新 \texttt{fmt} 文件后再编译 \texttt{tex} 文件.