laoyang/ouc_latex_template
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

开发环境迁移到 WSL 并修掉 Linux 上的跨版本兼容问题 #18

New Issue
Closed
opened 2026-10-29 03:59:36 +00:00 by laoyang · 1 comment
laoyang commented 2026-10-29 03:59:36 +00:00
Owner
Copy Link
Copy Source

开发环境迁移到 WSL 内，并修掉在 Linux/TeX Live 2025 上暴露的跨版本兼容问题

背景与诉求

开发环境整体搬到 WSL（Ubuntu 26.04 + TeX Live 2025）。要求：

  • 代码 clone 到 /home/yongquan/code/ouc_latex_template，全部放 WSL，通过远端 git 管理
  • 今后编译等操作都在 WSL 内进行
  • 编译完成后把 PDF 单独 scp 回 Windows

迁移中暴露的问题（Windows 端 TeX Live 2022 掩盖了它们）

1. 简历/ 的 babel[frenchb] 在 TeX Live 2025 上会失败

简历/awesome-source-cv.cls:51 写的是 \RequirePackage[frenchb]{babel}。

  • TeX Live 2022：通过
  • TeX Live 2025：报 ! Package babel Error: Unknown option 'frenchb'.
    即使压住这条，还会炸在 \begin{document} 处：
    ! Undefined control sequence. \__hook begindocument ...fter {\bbl@main@language }...

frenchb 是 babel 早期的法语方言名，新版本已从「已知语言」列表移除。

修法：改为 french。实测两个名字在旧版等价、新版只有 french 可用，属向前兼容写法。

2. FontAwesome 字体在 Debian/Ubuntu 的 texlive 里不随包分发

幻灯片/slides.tex:10、科技报告/report.tex:18 直接 \usepackage{fontawesome}，
而 fontawesome.sty:45 是 \newfontfamily{\FA}{FontAwesome} —— 按字体名加载。

  • TeX Live 官方发行版：把 FontAwesome.otf 放在 fonts/opentype/public/fontawesome/，fontspec 找得到
  • Debian/Ubuntu 的 texlive-fonts-extra：只装 .sty 与 symbols 定义，不带那个 .otf
    → 报 Package fontspec Error: The font "FontAwesome" cannot be found.

处理：不改模板源码，改为在 WSL 侧把仓库自带的 fonts/fontawesome/FontAwesome.otf
注册进 ~/.local/share/fonts/ 并 fc-cache。这样源码保持跨平台一致，
本库「字体只有一份来源」的设计不被破坏。

备注：简历/ 目录里已有一份改过路径的 fontawesome.sty（显式 Path=../fonts/fontawesome/）。
幻灯片与科技报告没有这份本地副本，走的是系统 sty，故需要 fontconfig 侧解决。
曾尝试在 .tex 里 \usepackage 之后加 \renewfontfamily 重定向 —— 无效，
因为 \usepackage{fontawesome} 执行到那一行就立刻加载字体并报错了，重定向来不及。已回退该改动。

3. 简历/ 还需要 texlive-lang-french

frenchb/french 选项都要求 frenchb.ldf，Debian 分在单独的 texlive-lang-french（140 KB）。

验收标准

  • 简历/awesome-source-cv.cls 的 babel 选项改为 french，并在注释里写明原因
  • WSL 内 13 个主文件全部编译通过（0 error），页数与 Windows 端一致
  • Windows 端回归不受影响（french 在 TeX Live 2022 上同样可用）
  • 建立「WSL 编译 → scp 取回 PDF」的工作流脚本
  • 验证产生的 PDF 不提交（时间戳差异会导致 12 个 PDF 全变）
  • 编译产物（.aux/.log/.cvnum 等）已被 .gitignore 覆盖，不污染仓库

环境记录

项 值
发行版 Ubuntu 26.04.1 LTS (WSL2)
TeX XeTeX 3.141592653-2.6-0.999997 (TeX Live 2025/Debian)
连接方式 ssh -i ~/.ssh/wsl_local yongquan@127.0.0.1（wsl.exe 被安全策略禁用）
仓库 /home/yongquan/code/ouc_latex_template，166 MB，160 文件
凭证 token 移出 remote URL，改用 ~/.git-credentials（权限 600）
开发环境迁移到 WSL 内，并修掉在 Linux/TeX Live 2025 上暴露的跨版本兼容问题 ## 背景与诉求 开发环境整体搬到 WSL（Ubuntu 26.04 + TeX Live 2025）。要求： - 代码 clone 到 `/home/yongquan/code/ouc_latex_template`，全部放 WSL，通过远端 git 管理 - 今后编译等操作都在 WSL 内进行 - 编译完成后把 PDF 单独 scp 回 Windows ## 迁移中暴露的问题（Windows 端 TeX Live 2022 掩盖了它们） ### 1. `简历/` 的 `babel[frenchb]` 在 TeX Live 2025 上会失败 `简历/awesome-source-cv.cls:51` 写的是 `\RequirePackage[frenchb]{babel}`。 - TeX Live 2022：通过 - TeX Live 2025：报 `! Package babel Error: Unknown option 'frenchb'.` 即使压住这条，还会炸在 `\begin{document}` 处： `! Undefined control sequence. \__hook begindocument ...fter {\bbl@main@language }...` `frenchb` 是 babel 早期的法语方言名，新版本已从「已知语言」列表移除。 **修法**：改为 `french`。实测两个名字在旧版等价、新版只有 `french` 可用，属向前兼容写法。 ### 2. `FontAwesome` 字体在 Debian/Ubuntu 的 texlive 里不随包分发 `幻灯片/slides.tex:10`、`科技报告/report.tex:18` 直接 `\usepackage{fontawesome}`， 而 `fontawesome.sty:45` 是 `\newfontfamily{\FA}{FontAwesome}` —— 按**字体名**加载。 - TeX Live 官方发行版：把 `FontAwesome.otf` 放在 `fonts/opentype/public/fontawesome/`，fontspec 找得到 - Debian/Ubuntu 的 `texlive-fonts-extra`：只装 `.sty` 与 symbols 定义，**不带那个 .otf** → 报 `Package fontspec Error: The font "FontAwesome" cannot be found.` **处理**：不改模板源码，改为在 WSL 侧把仓库自带的 `fonts/fontawesome/FontAwesome.otf` 注册进 `~/.local/share/fonts/` 并 `fc-cache`。这样源码保持跨平台一致， 本库「字体只有一份来源」的设计不被破坏。 > 备注：`简历/` 目录里已有一份改过路径的 `fontawesome.sty`（显式 `Path=../fonts/fontawesome/`）。 > 幻灯片与科技报告没有这份本地副本，走的是系统 sty，故需要 fontconfig 侧解决。 > 曾尝试在 `.tex` 里 `\usepackage` 之后加 `\renewfontfamily` 重定向 —— **无效**， > 因为 `\usepackage{fontawesome}` 执行到那一行就立刻加载字体并报错了，重定向来不及。已回退该改动。 ### 3. `简历/` 还需要 `texlive-lang-french` `frenchb`/`french` 选项都要求 `frenchb.ldf`，Debian 分在单独的 `texlive-lang-french`（140 KB）。 ## 验收标准 - [ ] `简历/awesome-source-cv.cls` 的 babel 选项改为 `french`，并在注释里写明原因 - [ ] WSL 内 13 个主文件全部编译通过（0 error），页数与 Windows 端一致 - [ ] Windows 端回归不受影响（`french` 在 TeX Live 2022 上同样可用） - [ ] 建立「WSL 编译 → scp 取回 PDF」的工作流脚本 - [ ] 验证产生的 PDF 不提交（时间戳差异会导致 12 个 PDF 全变） - [ ] 编译产物（`.aux`/`.log`/`.cvnum` 等）已被 `.gitignore` 覆盖，不污染仓库 ## 环境记录 | 项 | 值 | |---|---| | 发行版 | Ubuntu 26.04.1 LTS (WSL2) | | TeX | XeTeX 3.141592653-2.6-0.999997 (TeX Live 2025/Debian) | | 连接方式 | `ssh -i ~/.ssh/wsl_local yongquan@127.0.0.1`（`wsl.exe` 被安全策略禁用） | | 仓库 | `/home/yongquan/code/ouc_latex_template`，166 MB，160 文件 | | 凭证 | token 移出 remote URL，改用 `~/.git-credentials`（权限 600） |
laoyang commented 2026-10-29 04:03:47 +00:00
Author
Owner
Copy Link
Copy Source

WSL 迁移完成，全库 13 个模板编译验证通过。

环境

项 值
发行版 Ubuntu 26.04.1 LTS (WSL2)
TeX XeTeX 3.141592653-2.6-0.999997 (TeX Live 2025/Debian)
仓库 /home/yongquan/code/ouc_latex_template
连入方式 ssh -i ~/.ssh/wsl_local yongquan@127.0.0.1（wsl.exe 被沙箱安全策略禁用，改走 sshd）
凭证 token 已移出 remote URL，改用 ~/.git-credentials（600）

验收结果

13 个主文件全部 rc=0、error=0，页数与 Windows 端（TeX Live 2022）逐个一致：

劳务发放说明表 1 | 年度考核登记表 2 | 幻灯片 30 | 成绩构成说明 1
特殊事项说明表 1 | 科技报告 10 | 简历 3 | 试卷题型示例 6
参考答案与评分标准 3 | 试卷归档封面 1 | 试卷归档目录 1
课程执行大纲 5 | 课程教学日历 2

已知既有警告（非本次引入，与 Windows 端相同）：试卷/参考答案与评分标准示例 1 Overfull、
课程执行大纲 1 Overfull、幻灯片 1 Underfull、科技报告 1 Underfull。

改动

  1. 简历/awesome-source-cv.cls：babel[frenchb] → babel[french]。
    frenchb 是 babel 旧方言名，TeX Live 2025 已移除，写旧名会报
    Unknown option 'frenchb'，压住后进一步炸在 \begin{document} 的
    \bbl@main@language。french 在旧版本上等价，属向前兼容写法。

  2. 新增 build.sh：WSL 内编译 + scp 取回 PDF，支持单模板与 all。
    路径全部走环境变量覆盖（WSL_HOST/WSL_KEY/WSL_ROOT/WIN_ROOT/TEXBIN），
    不硬编码个人目录。

  3. 新增 verify_all.sh：批量编译验证，打印 error / Overfull / Underfull / 页数。
    每个模板在自己目录下编译（../fonts/ 是相对编译工作目录解析的）。

  4. 新增 .gitattributes：.sh 钉 eol=lf。Windows 侧 core.autocrlf=true
    会把脚本存成 CRLF，到 Linux 上执行报 /bin/bash^M: bad interpreter ——
    这个错容易误判成"没装 bash"，所以在仓库层面固定规则。

两个不属于模板 bug 的环境差异（记录备查）

① FontAwesome.otf 不随 Debian 的 texlive 分发

fontawesome.sty:45 是 \newfontfamily{\FA}{FontAwesome}，按字体名加载。
TeX Live 官方发行版把 .otf 放在 fonts/opentype/public/fontawesome/，
fontspec 找得到；Debian 的 texlive-fonts-extra 只装 .sty 与 symbols，不带那个 .otf。

处理：把仓库自带的 fonts/fontawesome/FontAwesome.otf 拷进 ~/.local/share/fonts/
并 fc-cache，让 fontconfig 认识它。不改模板源码，保持跨平台一致、
不破坏"字体只有一份来源"的设计。

踩坑记录：曾在 .tex 里 \usepackage{fontawesome} 之后加 \renewfontfamily 重定向 ——
无效。\usepackage 执行到内部那行就立刻加载字体并报错了，重定向来不及。该改动已回退。

② 简历/ 需要 texlive-lang-french（140 KB）

babel 的 french 选项要 frenchb.ldf，Debian 分在单独包里。

一个重要的运维发现

WSL2 会按「空闲」把整机 poweroff，nohup / systemd-run 都救不了。

迁移过程中 texlive-full 的安装被杀了三次，journal 显示 5 次开关机：

10:45:45 → 10:46:12    10:46:21 → 10:48:03    10:48:18 → 10:48:37
10:51:41 → 11:38:51   ← 装到一半被 poweroff，apt 连同 PID 1 一起消失
11:39:07 → 现在
  • .wslconfig 里虽已写 instanceIdleTimeout=-1 / vmIdleTimeout=-1，
    但那是 11:35:21 写入的，而 WSL 启于 10:51:41，改完必须 wsl --shutdown
    重启才加载    ，所以当时并未生效。
  • wsl.exe 被沙箱禁用，无法自行触发 shutdown。
  • 结论：编译/安装类长任务必须在保持不断的 ssh 会话里跑（build.sh 就是这么
    设计的，不要改成后台运行）；或由用户在 Windows 侧 wsl --shutdown 一次让
    新 .wslconfig 生效。

另外：texlive-full 把 11 个 -doc 包列为硬依赖（其中 latex-extra-doc
单包 815 MB，纯 PDF 手册），而它们对功能包只是 Suggests。最终改用功能全集
（排除全部 -doc）+ --no-install-recommends，装完 824 个 texlive 包，
编译能力与 full 等价。

提交：1c27041、ef1bc72、8660860，均已推送。

WSL 迁移完成，全库 13 个模板编译验证通过。 ## 环境 | 项 | 值 | |---|---| | 发行版 | Ubuntu 26.04.1 LTS (WSL2) | | TeX | XeTeX 3.141592653-2.6-0.999997 (TeX Live 2025/Debian) | | 仓库 | `/home/yongquan/code/ouc_latex_template` | | 连入方式 | `ssh -i ~/.ssh/wsl_local yongquan@127.0.0.1`（`wsl.exe` 被沙箱安全策略禁用，改走 sshd） | | 凭证 | token 已移出 remote URL，改用 `~/.git-credentials`（600） | ## 验收结果 13 个主文件全部 `rc=0`、`error=0`，页数与 Windows 端（TeX Live 2022）**逐个一致**： ``` 劳务发放说明表 1 | 年度考核登记表 2 | 幻灯片 30 | 成绩构成说明 1 特殊事项说明表 1 | 科技报告 10 | 简历 3 | 试卷题型示例 6 参考答案与评分标准 3 | 试卷归档封面 1 | 试卷归档目录 1 课程执行大纲 5 | 课程教学日历 2 ``` 已知既有警告（非本次引入，与 Windows 端相同）：`试卷/参考答案与评分标准示例` 1 Overfull、 `课程执行大纲` 1 Overfull、`幻灯片` 1 Underfull、`科技报告` 1 Underfull。 ## 改动 1. **`简历/awesome-source-cv.cls`**：`babel[frenchb]` → `babel[french]`。 `frenchb` 是 babel 旧方言名，TeX Live 2025 已移除，写旧名会报 `Unknown option 'frenchb'`，压住后进一步炸在 `\begin{document}` 的 `\bbl@main@language`。`french` 在旧版本上等价，属向前兼容写法。 2. **新增 `build.sh`**：WSL 内编译 + `scp` 取回 PDF，支持单模板与 `all`。 路径全部走环境变量覆盖（`WSL_HOST`/`WSL_KEY`/`WSL_ROOT`/`WIN_ROOT`/`TEXBIN`）， 不硬编码个人目录。 3. **新增 `verify_all.sh`**：批量编译验证，打印 error / Overfull / Underfull / 页数。 每个模板在自己目录下编译（`../fonts/` 是相对编译工作目录解析的）。 4. **新增 `.gitattributes`**：`.sh` 钉 `eol=lf`。Windows 侧 `core.autocrlf=true` 会把脚本存成 CRLF，到 Linux 上执行报 `/bin/bash^M: bad interpreter` —— 这个错容易误判成"没装 bash"，所以在仓库层面固定规则。 ## 两个不属于模板 bug 的环境差异（记录备查） **① `FontAwesome.otf` 不随 Debian 的 texlive 分发** `fontawesome.sty:45` 是 `\newfontfamily{\FA}{FontAwesome}`，按字体名加载。 TeX Live 官方发行版把 `.otf` 放在 `fonts/opentype/public/fontawesome/`， fontspec 找得到；Debian 的 `texlive-fonts-extra` 只装 `.sty` 与 symbols，**不带那个 .otf**。 处理：把仓库自带的 `fonts/fontawesome/FontAwesome.otf` 拷进 `~/.local/share/fonts/` 并 `fc-cache`，让 fontconfig 认识它。**不改模板源码**，保持跨平台一致、 不破坏"字体只有一份来源"的设计。 > 踩坑记录：曾在 `.tex` 里 `\usepackage{fontawesome}` 之后加 `\renewfontfamily` 重定向 —— > **无效**。`\usepackage` 执行到内部那行就立刻加载字体并报错了，重定向来不及。该改动已回退。 **② `简历/` 需要 `texlive-lang-french`（140 KB）** `babel` 的 `french` 选项要 `frenchb.ldf`，Debian 分在单独包里。 ## 一个重要的运维发现 **WSL2 会按「空闲」把整机 poweroff，`nohup` / `systemd-run` 都救不了。** 迁移过程中 `texlive-full` 的安装被杀了三次，journal 显示 5 次开关机： ``` 10:45:45 → 10:46:12 10:46:21 → 10:48:03 10:48:18 → 10:48:37 10:51:41 → 11:38:51 ← 装到一半被 poweroff，apt 连同 PID 1 一起消失 11:39:07 → 现在 ``` - `.wslconfig` 里虽已写 `instanceIdleTimeout=-1` / `vmIdleTimeout=-1`， 但那是 **11:35:21** 写入的，而 WSL 启于 10:51:41，**改完必须 `wsl --shutdown` 重启才加载**，所以当时并未生效。 - `wsl.exe` 被沙箱禁用，无法自行触发 shutdown。 - 结论：**编译/安装类长任务必须在保持不断的 ssh 会话里跑**（`build.sh` 就是这么 设计的，不要改成后台运行）；或由用户在 Windows 侧 `wsl --shutdown` 一次让 新 `.wslconfig` 生效。 另外：`texlive-full` 把 11 个 `-doc` 包列为**硬依赖**（其中 `latex-extra-doc` 单包 815 MB，纯 PDF 手册），而它们对功能包只是 `Suggests`。最终改用功能全集 （排除全部 `-doc`）+ `--no-install-recommends`，装完 824 个 texlive 包， 编译能力与 full 等价。 提交：`1c27041`、`ef1bc72`、`8660860`，均已推送。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
laoyang (老杨)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: laoyang/ouc_latex_template#18