LaTeX新手避坑实录在LinuxUbuntu/Debian安装TeXLive 2024时我踩过的那些‘坑’第一次在Linux上安装TeXLive的经历简直像一场充满未知陷阱的冒险。作为从Windows转战Ubuntu的LaTeX新手我原以为按照教程一步步操作就能顺利完成没想到从下载镜像到配置VSCode几乎每个环节都遇到了意想不到的问题。这篇文章记录了我踩过的那些坑以及如何一步步爬出来的实战经验。1. 镜像下载速度慢与挂载失败的终极解决方案刚开始安装就遇到了第一个拦路虎——TeXLive的ISO镜像下载速度堪比蜗牛。官方推荐的镜像源在我这里只有50KB/s的速度一个3GB的文件要下载十几个小时。更糟的是好不容易下载完成后挂载时又出现了mount: /mnt: WARNING: device write-protected, mounted read-only.的警告。1.1 国内镜像源替代方案经过多次尝试我发现以下几个国内镜像源速度最快清华大学镜像站https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/Images/中国科学技术大学镜像https://mirrors.ustc.edu.cn/CTAN/systems/texlive/Images/华为云镜像https://repo.huaweicloud.com/texlive/Images/使用curl下载的命令应改为curl -L https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/Images/texlive2024.iso -o texlive.iso1.2 挂载问题的排查与修复当遇到挂载警告时不要惊慌。这个警告只是提示设备是只读的属于正常现象。真正需要担心的是以下错误错误1mount: /mnt: no such file or directory解决方案先创建挂载点目录sudo mkdir -p /mnt错误2mount: /mnt: mount failed: Operation not permitted解决方案检查ISO文件完整性重新下载md5sum texlive.iso2. Perl模块依赖cpanm安装报错全解析安装完TeXLive基础环境后配置VSCode的LaTeX Workshop插件时需要安装几个Perl模块。这里我遇到了各种依赖问题特别是使用cpanm安装时。2.1 必须的Perl模块列表以下是LaTeX Workshop正常运行所需的核心Perl模块YAML::TinyFile::HomeDirUnicode::GCStringLog::Log4perlLog::Dispatch2.2 常见错误及解决方法错误1Cant locate ExtUtils/MakeMaker.pm这是基础开发工具缺失的表现需要先安装Perl开发环境sudo apt install perl-modules-5.30错误2Failed to build Log::Log4perl这个问题通常是因为缺少测试依赖可以跳过测试安装sudo cpanm --notest Log::Log4perl错误3Warning: prerequisite Test::Pod 1.14 not found安装测试相关模块sudo cpanm Test::Pod3. VSCode配置编译失败与搜索失效的深度排查配置VSCode的LaTeX环境时我遇到了最棘手的问题——编译能通过但PDF无法显示正向/反向搜索完全失效。3.1 LaTeX Workshop配置要点以下是我的最终有效配置settings.json{ latex-workshop.latex.recipes: [ { name: xelatex, tools: [xelatex] } ], latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] } ], latex-workshop.view.pdf.viewer: tab, latex-workshop.latex.autoBuild.run: onFileChange }3.2 正向/反向搜索失效解决方案确保SyncTeX已安装tlmgr install synctex检查PDF阅读器配置在VSCode中设置latex-workshop.view.pdf.external.viewer.args为正确的参数对于Evince使用latex-workshop.view.pdf.external.viewer.command: evince, latex-workshop.view.pdf.external.viewer.args: [ --synctex-forward, %LINE%:%COLUMN%:%PDF% ]重建索引文件xelatex -synctex1 yourfile.tex4. 环境变量配置命令找不到的终极修复安装完成后最令人抓狂的就是输入tex或latex命令时提示command not found。4.1 正确的环境变量设置在~/.bashrc末尾添加根据实际安装年份调整export PATH/usr/local/texlive/2024/bin/x86_64-linux:$PATH export MANPATH/usr/local/texlive/2024/texmf-dist/doc/man:$MANPATH export INFOPATH/usr/local/texlive/2024/texmf-dist/doc/info:$INFOPATH4.2 常见问题排查问题1修改.bashrc后命令仍无效解决方案执行source ~/.bashrc或重新打开终端问题2路径拼写错误检查路径是否存在ls /usr/local/texlive/2024/bin/x86_64-linux问题3多版本冲突如果系统自带了旧版TeXLive需要先卸载sudo apt remove texlive-*5. 字体配置中文字体显示异常的解决之道使用xelatex编译中文文档时最常见的坑就是字体问题。明明系统安装了中文字体LaTeX却提示找不到。5.1 字体配置步骤确认字体已安装fc-list :langzh在LaTeX文档中正确指定字体\usepackage{fontspec} \setmainfont{Noto Serif CJK SC}更新TeXLive字体映射sudo mktexlsr5.2 常见中文字体包ctex宏包一站式解决方案xeCJK更灵活的配置fontspec直接调用系统字体6. 实用技巧与优化建议经过这次折腾我总结出几个能大幅提升LaTeX使用体验的技巧使用tlmgr管理宏包tlmgr update --self tlmgr install package定期更新tlmgr update --all清理临时文件latexmk -c使用latexmk自动化编译latexmk -xelatex yourfile.tex配置VSCode任务 在.vscode/tasks.json中添加LaTeX编译任务实现一键编译。折腾LaTeX环境的过程虽然痛苦但解决问题的成就感无与伦比。现在我的Ubuntu系统上已经建立了一套稳定高效的LaTeX工作环境写论文再也不用担心格式问题了。
LaTeX新手避坑实录：在Linux（Ubuntu/Debian）安装TeXLive 2024时我踩过的那些‘坑’
LaTeX新手避坑实录在LinuxUbuntu/Debian安装TeXLive 2024时我踩过的那些‘坑’第一次在Linux上安装TeXLive的经历简直像一场充满未知陷阱的冒险。作为从Windows转战Ubuntu的LaTeX新手我原以为按照教程一步步操作就能顺利完成没想到从下载镜像到配置VSCode几乎每个环节都遇到了意想不到的问题。这篇文章记录了我踩过的那些坑以及如何一步步爬出来的实战经验。1. 镜像下载速度慢与挂载失败的终极解决方案刚开始安装就遇到了第一个拦路虎——TeXLive的ISO镜像下载速度堪比蜗牛。官方推荐的镜像源在我这里只有50KB/s的速度一个3GB的文件要下载十几个小时。更糟的是好不容易下载完成后挂载时又出现了mount: /mnt: WARNING: device write-protected, mounted read-only.的警告。1.1 国内镜像源替代方案经过多次尝试我发现以下几个国内镜像源速度最快清华大学镜像站https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/Images/中国科学技术大学镜像https://mirrors.ustc.edu.cn/CTAN/systems/texlive/Images/华为云镜像https://repo.huaweicloud.com/texlive/Images/使用curl下载的命令应改为curl -L https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/Images/texlive2024.iso -o texlive.iso1.2 挂载问题的排查与修复当遇到挂载警告时不要惊慌。这个警告只是提示设备是只读的属于正常现象。真正需要担心的是以下错误错误1mount: /mnt: no such file or directory解决方案先创建挂载点目录sudo mkdir -p /mnt错误2mount: /mnt: mount failed: Operation not permitted解决方案检查ISO文件完整性重新下载md5sum texlive.iso2. Perl模块依赖cpanm安装报错全解析安装完TeXLive基础环境后配置VSCode的LaTeX Workshop插件时需要安装几个Perl模块。这里我遇到了各种依赖问题特别是使用cpanm安装时。2.1 必须的Perl模块列表以下是LaTeX Workshop正常运行所需的核心Perl模块YAML::TinyFile::HomeDirUnicode::GCStringLog::Log4perlLog::Dispatch2.2 常见错误及解决方法错误1Cant locate ExtUtils/MakeMaker.pm这是基础开发工具缺失的表现需要先安装Perl开发环境sudo apt install perl-modules-5.30错误2Failed to build Log::Log4perl这个问题通常是因为缺少测试依赖可以跳过测试安装sudo cpanm --notest Log::Log4perl错误3Warning: prerequisite Test::Pod 1.14 not found安装测试相关模块sudo cpanm Test::Pod3. VSCode配置编译失败与搜索失效的深度排查配置VSCode的LaTeX环境时我遇到了最棘手的问题——编译能通过但PDF无法显示正向/反向搜索完全失效。3.1 LaTeX Workshop配置要点以下是我的最终有效配置settings.json{ latex-workshop.latex.recipes: [ { name: xelatex, tools: [xelatex] } ], latex-workshop.latex.tools: [ { name: xelatex, command: xelatex, args: [ -synctex1, -interactionnonstopmode, -file-line-error, %DOC% ] } ], latex-workshop.view.pdf.viewer: tab, latex-workshop.latex.autoBuild.run: onFileChange }3.2 正向/反向搜索失效解决方案确保SyncTeX已安装tlmgr install synctex检查PDF阅读器配置在VSCode中设置latex-workshop.view.pdf.external.viewer.args为正确的参数对于Evince使用latex-workshop.view.pdf.external.viewer.command: evince, latex-workshop.view.pdf.external.viewer.args: [ --synctex-forward, %LINE%:%COLUMN%:%PDF% ]重建索引文件xelatex -synctex1 yourfile.tex4. 环境变量配置命令找不到的终极修复安装完成后最令人抓狂的就是输入tex或latex命令时提示command not found。4.1 正确的环境变量设置在~/.bashrc末尾添加根据实际安装年份调整export PATH/usr/local/texlive/2024/bin/x86_64-linux:$PATH export MANPATH/usr/local/texlive/2024/texmf-dist/doc/man:$MANPATH export INFOPATH/usr/local/texlive/2024/texmf-dist/doc/info:$INFOPATH4.2 常见问题排查问题1修改.bashrc后命令仍无效解决方案执行source ~/.bashrc或重新打开终端问题2路径拼写错误检查路径是否存在ls /usr/local/texlive/2024/bin/x86_64-linux问题3多版本冲突如果系统自带了旧版TeXLive需要先卸载sudo apt remove texlive-*5. 字体配置中文字体显示异常的解决之道使用xelatex编译中文文档时最常见的坑就是字体问题。明明系统安装了中文字体LaTeX却提示找不到。5.1 字体配置步骤确认字体已安装fc-list :langzh在LaTeX文档中正确指定字体\usepackage{fontspec} \setmainfont{Noto Serif CJK SC}更新TeXLive字体映射sudo mktexlsr5.2 常见中文字体包ctex宏包一站式解决方案xeCJK更灵活的配置fontspec直接调用系统字体6. 实用技巧与优化建议经过这次折腾我总结出几个能大幅提升LaTeX使用体验的技巧使用tlmgr管理宏包tlmgr update --self tlmgr install package定期更新tlmgr update --all清理临时文件latexmk -c使用latexmk自动化编译latexmk -xelatex yourfile.tex配置VSCode任务 在.vscode/tasks.json中添加LaTeX编译任务实现一键编译。折腾LaTeX环境的过程虽然痛苦但解决问题的成就感无与伦比。现在我的Ubuntu系统上已经建立了一套稳定高效的LaTeX工作环境写论文再也不用担心格式问题了。
