基于CodeServer打造一个属于自己的 LaTeX Web 编辑器

教程：打造一个属于自己的 LaTeX Web 编辑器

一、为什么不用 Overleaf？

Overleaf 虽然功能强大且易于上手，但存在以下局限：

服务器在国外：访问速度慢，尤其在国内网络环境下体验不佳；
自建 Overleaf 麻烦：部署复杂，依赖较多，维护成本高；
功能受限：部分高级功能需付费，且无法完全自定义环境。

因此，我们选择基于开源工具自建一个轻量、高效、可定制的 LaTeX Web 编辑器。

二、整体思路

我们将使用以下技术栈构建：

code-server：VS Code 的 Web 版本，可在浏览器中运行 VS Code；
TeX Live（完整版）：提供完整的 LaTeX 编译环境；
Docker + Docker Compose：实现一键部署、环境隔离与快速迁移；
LaTeX Workshop 插件：为 VS Code 提供强大的 LaTeX 支持。

最终效果：通过浏览器访问 http://你的服务器IP:8002，即可使用功能齐全的 LaTeX 编辑器。

三、创建 Dockerfile

Dockerfile 用于构建包含 code-server 和完整 LaTeX 环境的镜像。

dockerfile 复制代码

# 基于官方 code-server 镜像（LinuxServer 维护）
FROM linuxserver/code-server:4.103.2

# 切换到 root 用户以安装系统包
USER root

# 替换 APT 源为阿里云镜像，加速国内下载
RUN if [ -f /etc/apt/sources.list ]; then \
        sed -i 's@http://.*ubuntu.com@http://mirrors.aliyun.com@g' /etc/apt/sources.list; \
    elif [ -f /etc/apt/sources.list.d/debian.sources ]; then \
        sed -i 's@http://.*debian.org@http://mirrors.aliyun.com@g' /etc/apt/sources.list.d/debian.sources; \
    else \
        echo "无法找到APT源文件，将使用默认源"; \
    fi

# 安装完整版 TeX Live（包含所有宏包）
RUN apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
    texlive-full \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# 安装中文字体支持（文泉驿微米黑 & 正黑）
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    fonts-wqy-microhei \
    fonts-wqy-zenhei \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# 切回非 root 用户（code-server 推荐做法）
USER coder

💡 说明：texlive-full 体积较大（约 5GB+），但能避免"缺少宏包"的常见问题。若追求精简，可改用 texlive-latex-extra + 手动安装所需包。

四、编写 docker-compose.yaml

用于一键启动服务：

yaml 复制代码

version: '3.8'

services:
  code:
    image: latex-vscode:latest          # 使用上一步构建的镜像
    container_name: latex-vscode
    restart: always
    networks:
      - 1panel-network                  # 使用 1Panel 创建的外部网络（可替换为 bridge）
    ports:
      - "8002:8443"                     # 映射 HTTPS 端口（code-server 默认 8443）
    volumes:
      - ./data/config:/config           # 配置持久化
      - ./data/workspace:/workspace     # 工作区持久化
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - PASSWORD=123456                 # 登录密码
      - SUDO_PASSWORD=sudo123           # sudo 密码（如需）
    user: "1000:1000"                   # 指定容器内运行用户
    labels:
      createdBy: "Apps"

networks:
  1panel-network:
    external: true                      # 若未使用 1Panel，可改为 internal 或删除此段

✅ 提示：

如未使用 1Panel，可将 networks 部分简化为 network_mode: bridge；

端口 8002 可根据需要修改；

密码 123456 建议在生产环境中更换为强密码。

五、构建并启动服务

构建镜像：
bash 复制代码
```
docker build -t latex-vscode .
```
启动服务：
bash 复制代码
```
docker-compose up -d
```
访问 Web 编辑器：
- 浏览器打开：https://你的服务器IP:8002
- 输入密码：123456（或你在 compose 文件中设置的密码）

🔒 注意：code-server 默认使用 HTTPS，首次访问浏览器可能会提示"不安全"，选择"继续访问"即可。

六、安装并配置 LaTeX Workshop 插件

在 code-server 中打开扩展商店（Extensions）；
搜索并安装 LaTeX Workshop；
按 Ctrl + Shift + P，输入 Open Settings (JSON)，打开 settings.json；
添加以下配置（已优化中文与编译体验）：

json 复制代码

// ------------------------------ LaTeX 配置 ----------------------------------
// 禁用自动编译（按需手动触发）
"latex-workshop.latex.autoBuild.run": "never",

// 启用右键菜单
"latex-workshop.showContextMenu": true,

// 启用从宏包中自动补全命令和环境
"latex-workshop.intellisense.package.enabled": true,

// 关闭错误/警告气泡提示（减少干扰）
"latex-workshop.message.error.show": false,
"latex-workshop.message.warning.show": false,

// 编译工具定义
"latex-workshop.latex.tools": [
  {
    "name": "xelatex",
    "command": "xelatex",
    "args": ["-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOCFILE%"]
  },
  {
    "name": "pdflatex",
    "command": "pdflatex",
    "args": ["-synctex=1", "-interaction=nonstopmode", "-file-line-error", "%DOCFILE%"]
  },
  {
    "name": "latexmk",
    "command": "latexmk",
    "args": ["-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-pdf", "-outdir=%OUTDIR%", "%DOCFILE%"]
  },
  {
    "name": "bibtex",
    "command": "bibtex",
    "args": ["%DOCFILE%"]
  }
],

// 编译配方（Recipes）
"latex-workshop.latex.recipes": [
  { "name": "XeLaTeX", "tools": ["xelatex"] },
  { "name": "PDFLaTeX", "tools": ["pdflatex"] },
  { "name": "BibTeX", "tools": ["bibtex"] },
  { "name": "LaTeXmk", "tools": ["latexmk"] },
  {
    "name": "xelatex → bibtex → xelatex×2",
    "tools": ["xelatex", "bibtex", "xelatex", "xelatex"]
  },
  {
    "name": "pdflatex → bibtex → pdflatex×2",
    "tools": ["pdflatex", "bibtex", "pdflatex", "pdflatex"]
  }
],

// 清理辅助文件类型
"latex-workshop.latex.clean.fileTypes": [
  "*.aux", "*.bbl", "*.blg", "*.idx", "*.ind", "*.lof", "*.lot", "*.out", "*.toc",
  "*.acn", "*.acr", "*.alg", "*.glg", "*.glo", "*.gls", "*.ist", "*.fls", "*.log", "*.fdb_latexmk"
],

// 构建失败后自动清理
"latex-workshop.latex.autoClean.run": "onFailed",

// 默认使用上次使用的编译配方
"latex-workshop.latex.recipe.default": "lastUsed",

// PDF 内部查看器：双击实现反向同步（源码 ↔ PDF）
"latex-workshop.view.pdf.internal.synctex.keybinding": "double-click"

七、使用建议

新建 .tex 文件后，点击左侧 LaTeX 图标，选择"Recipe: XeLaTeX"进行编译；
中文文档推荐使用 XeLaTeX 引擎，并在导言区加载 fontspec 或 ctex 宏包；
所有项目文件保存在 ./data/workspace 目录下，可直接通过服务器文件系统管理。

八、总结

通过本教程，你成功搭建了一个：

✅ 功能完整

✅ 支持中文

✅ 可远程访问

✅ 可持久化存储

✅ 可自定义配置

的 私有 LaTeX Web 编辑器，摆脱对 Overleaf 的依赖，真正实现"自己的编辑器自己做主"！